Miscellenous
Using the API
Append to response
append_to_response is an easy and efficient way to append extra requests to any top level namespace. The movie, TV show, TV season, TV episode and person detail methods all support a query parameter called append_to_response. This makes it possible to make sub requests within the same namespace in a single HTTP request. Each request will get appended to the response as a new JSON object.
Here’s a quick example, let’s assume you want the movie details and the videos for a movie. Usually you would think you have to issue two requests:
But with append_to_response you can issue a single request:
Even more powerful, you can issue multiple requests, just comma separate the values:
Each method will still respond to whatever query parameters are supported by each individual request. This is worth pointing out specifically for images since your language parameter will filter images. This is where the include_image_language parameter can be useful as outlined in the image language page.
Daily ID Exports
Download a list of valid IDs from TMDB.
We currently publish a set of daily ID file exports. These are not, nor intended to be full data exports. Instead, they contain a list of the valid IDs you can find on TMDB and some higher level attributes that are helpful for filtering items like the adult, video and popularity values.
Data Structure
These files themselves are not a valid JSON object. Instead, each line is. Most systems, tools and languages have easy ways of scanning lines in files (skipping and buffering) without having to load the entire file into memory. The assumption here is that you can read every line easily, and you can expect each line to contain a valid JSON object.
Availability
All of the exported files are available for download from http://files.tmdb.org. The export job runs every day starting at around 7:00 AM UTC, and all files are available by 8:00 AM UTC.
There is currently no authentication on these files since they are not very useful unless you’re a user of our service. Please note that this could change at some point in the future so if you start having problems accessing these files, check this document for updates.
These files are only made available for 3 months after which they are automatically deleted.
Media Type Path Name Movies /p/exports movie_ids_MM_DD_YYYY.json.gz TV Series /p/exports tv_series_ids_MM_DD_YYYY.json.gz People /p/exports person_ids_MM_DD_YYYY.json.gz Collections /p/exports collection_ids_MM_DD_YYYY.json.gz TV Networks /p/exports tv_network_ids_MM_DD_YYYY.json.gz Keywords /p/exports keyword_ids_MM_DD_YYYY.json.gz Production Companies /p/exports production_company_ids_MM_DD_YYYY.json.gz
Example
If you were looking for a list of valid movie ids, the full download URL for the file published on May 15, 2024 is located here:
http://files.tmdb.org/p/exports/movie_ids_05_15_2024.json.gz
Adult ID’s
Starting July 5, 2023, we are now also publishing the adult data set. You can find the paths for movies, TV shows and people below.
Media Type Path Name Movies /p/exports adult_movie_ids_MM_DD_YYYY.json.gz TV Series /p/exports adult_tv_series_ids_MM_DD_YYYY.json.gz People /p/exports adult_person_ids_MM_DD_YYYY.json.gz
Example
http://files.tmdb.org/p/exports/adult_movie_ids_05_15_2024.json.gz
Finding Data
How do you find data on TMDB?
There are 3 ways to search for and find movies, TV shows and people on TMDB. They’re outlined below.
/search- Text based search is the most common way. You provide a query string and we provide the closest match. Searching by text takes into account all original, translated, alternative names and titles./discover- Sometimes it useful to search for movies and TV shows based on filters or definable values like ratings, certifications or release dates. The discover method make this easy./find- The last but still very useful way to find data is with existing external IDs. For example, if you know the IMDB ID of a movie, TV show or person, you can plug that value into this method and we’ll return anything that matches. This can be very useful when you have an existing tool and are adding our service to the mix. Take a look at the search & query for details page for some basic workflows you might use to search and query data.
JSON & JSONP
The only response format we support is JSON.
If you are using a JavaScript library and need to make requests from another public domain, you can use the callback paramater which will encapsulate the JSON response in a JavaScript function for you.
Languages
Learn about languages on TMDB.
TMDB tries to be localized wherever possible. While most of our metadata endpoints support translated data, there are still a few gaps that do not. The two main areas that are not are person names and characters. We’re working to support this.
ISO 639-1
The language code system we use is ISO 639-1. Unfortunately, there are a number of languages that don’t have a ISO-639-1 representation. We may decide to upgrade to ISO-639-3 in the future but do not have any immediate plans to do so.
ISO 3166-1
You’ll usually find our language codes mated to a country code in the format of en-US. The country codes in use here are ISO 3166-1.
Images do not yet support the language-COUNTRY notation. This will be improved in the future. Take a read through the image language documentation to learn how to partly get around this limitation.
Now that you know how languages work, let’s look at some example requests.