Search & Query For Details

Learn how to search and query for a movie.

A common workflow on TMDB involves searching for a movie (or TV show, or person) and then retrieving its details.

Here’s a quick overview of how that process works:

1. Search

To begin, you’ll query for a movie, TV show, or person using the search methods.

We’ll use Jack Reacher and the movie endpoint for this example:

Example Search Request

curl --request GET \
    --url 'https://api.themoviedb.org/3/search/movie?query=Jack+Reacher' \
    --header 'Authorization: Bearer {ACCESS_TOKEN}'

This request returns an object, but the key you’ll want to focus on is the results array.

The results array contains standard movie list objects. Here’s an example of the first item:

Example Results Object

"results": [
    {
        "adult": false,
        "backdrop_path": "/2v3pC01rf0uXnECOM94pjfqk1TY.jpg",
        "genre_ids": [
            80,
            18,
            53,
            28
        ],
        "id": 75780,
        "original_language": "en",
        "original_title": "Jack Reacher",
        "overview": "One morning in an ordinary town, five people are shot dead in a seemingly random attack. All evidence points to a single suspect: an ex-military sniper who is quickly brought into custody. The interrogation yields one written note: 'Get Jack Reacher!'. Reacher, an enigmatic ex-Army investigator, believes the authorities have the right man but agrees to help the sniper's defense attorney. However, the more Reacher delves into the case, the less clear-cut it appears. So begins an extraordinary chase for the truth, pitting Jack Reacher against an unexpected enemy, with a skill for violence and a secret to keep.",
        "popularity": 40.197,
        "poster_path": "/gLv55839pz4lhyKGRaJKbty41yq.jpg",
        "release_date": "2012-12-20",
        "title": "Jack Reacher",
        "video": false,
        "vote_average": 6.6,
        "vote_count": 7086
    }
]

2. Query for Movie Details

With the item above in hand, you can see an id: 75780 this represent a movie ID. You can use this id to fetch for the movie detail like this:

Example Details Query

curl --request GET \
     --url 'https://api.themoviedb.org/3/movie/75780' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}'

This request returns all the main movie detail, as outlined in the movie details documentation.

For more efficiency, check out the append to response feature, which allows you to make multiple sub-requests in one. For example, to get videos along with movie details:

Example Append Request

curl --request GET \
     --url 'https://api.themoviedb.org/3/movie/75780?append_to_response=videos' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}'

This helps streamline your queries and reduce the number of API calls.