Fetchers

Fetchers are how you download data about a movie list from some external source.

When you configure a list, you will need to configure it with a listdef describing which fetcher to use, and the address of the list to download.

Some fetchers allow you to control additional fetch settings using --fetch-param.

Tip

Flam supports implementing custom fetchers.

List of builtin fetchers

imdb-listid=IMDB_LIST_ID

Takes an IMDb list ID as an input, and downloads information in two steps:

  1. Export the list to CSV from the IMDb website - this will automatically launch your browser and click some buttons!

  2. Fill in a bunch of additional information using this free API: https://imdbapi.dev/

It’s easy to check what is your list’s ID. Just open it in the browser, and the URL should look like this: https://www.imdb.com/list/ls083886771. The list ID in this example is “083886771”.

There are a few environment variables you can export to control the browser use:

  • FLAM_DOWNLOADS - Path to the downloads folder on your computer so flam will know where to look for the downloaded CSV.

    Warning

    If your browser doesn’t download things to ~/Downloads, you must set this variable for this fetcher to work!

  • FLAM_BROWSER - Which browser to use: ‘chrome’, ‘edge’, or ‘firefox’. By default flam tries to detect your default browser

  • FLAM_BROWSER_PROFILE - Path to your browser profile. This is only needed if your list is set to private so a profile is needed where you are expected to be already logged in.

This fetcher also supports one --fetch-param:

  • csv-path - Skip exporting the list to CSV in the browser and instead use this path to an already downloaded file. Path may contain environment variables (%USERPROFILE%, $HOME, etc.).

    Tip

    Use this option as a workaround if you’re having trouble with the automatic browser control feature. You will have to export the list manually.

letterboxd-user-list=LETTERBOXD_USER_LIST

Takes a Letterboxd user and list name in the form <username>/<list_slug> as an input, and downloads the list using letterboxdpy.

List slugs are just the list name as it appears in the list URL. Just open it in the browser, and the URL should look like this: https://letterboxd.com/verpous/list/movies-ive-watched/. The <username>/<list_slug> in this example is “verpous/movies-ive-watched”.

A few special lists are also supported:

  • <username>/films - the user’s watched films

  • <username>/likes - the user’s liked films

  • <username>/reviews - the user’s reviewed films

  • <username>/watchlist - the user’s watchlist

Note that Letterboxd provides us a lot of information about movies, but not so much about people. So this fetcher has a blindspot there.

tmdb-list=TMDB_LIST_ID

Takes a TMDB list ID as an input, and downloads the list using the TMDB API.

It’s easy to check what is your list’s ID. Just open it in the browser, and the URL should look like this: https://www.themoviedb.org/list/7103008-movies-i-ve-watched. The list ID in this example is “7103008”.

A few special list IDs are also supported:

  • favorite-movies

  • favorite-shows

  • rated-movies

  • rated-shows

  • watchlist-movies

  • watchlist-shows

In order to use this fetcher, you MUST have a TMDB API token, and export it to the environment. You can request an API token from your profile settings on TMDB.

Once you’ve been granted access, take the “API Read Access Token” from your profile page and assign it to an environment variable named FLAM_TMDB_API_TOKEN:

export FLAM_TMDB_API_TOKEN="abcdefgverylongstringofrandomcharacters"