TMDb API Documentation — Movie & Cast Information

2.1 Deprecation Notice!
Please be aware that the 2.1 version of our API has been deprecated. It has been replaced by v3. You can read the new API documentation here.

Movie.browse

The Movie.browse method is probably the most powerful single method on the entire TMDb API. While it might not be used by all apps, it is a great place to start if you're interested in building any kind of a top 10 list.

Some examples include getting a list of the top 'drama' movies, or maybe the top science fiction movies released since 2000. These are fairly simple examples as you can also add any number of extra attributes to your search. These are all passed as URL query parameters and are outlined below.

Example URL

http://api.themoviedb.org/2.1/Movie.browse/en-US/xml/APIKEY?order_by=rating&order=desc&genres=18&min_votes=5&page=1&per_page=10

Options

Language: IETF Language Tag, e.g. en-US

Type: Type can be xml, yaml or json.

API Key: The API key we supplied you with for your account.

Query parameters: The Movie.browse method has many query-able parameters. Here's an outline of what you can do with it.

order_by
3 options: rating, release, title
order
2 options: asc, desc

per_page
This value sets the number of results to display per page (or request). Without it, the default is 30 results. 'page' is required if you're using per_page. Value is expected to be an integer.
page
Results are paginated if you use the page & per_page parameters. You can quickly scan through multiple pages with these options. Value is expected to be an integer.
query
The search query parameter is used to search for some specific text from a title.
min_votes
Only return movies with a certain minimum number of votes. Expected value is an integer.
rating_min
If you'd only like to see movies with a certain minimum rating, use this. It is expected to be a float value and if used, rating_max is required.
rating_max
Used in conjunction with rating_min. Sets the upper limit of movies to return based on their rating. Expects this value to be a float.
genres
The genres parameter is to be passed the genres id(s) you want to search for. You can get these ids from the Genres.getList method. In the event you want to search for multiple genres, you have to pass the values as a comma separated value.
genres_selector
2 options: and, or

Used when you search for more than 1 genre and useful to combine your genre searches.
release_min
Useful if you'd like to only search for movies from a particular date and on. If used, rating_max is required. The value is expected to be an epoch value.
release_max
Sets the upper date limit to search for. Like release_min this is expected to be an epoch value and if used, release_min is required.
year
If you'd only like to search for movies from a particular year, this if your option. Expects a single integer value.
certifications
Like genres, you can pass multiple values to this option. Comma separate them in this case. The values to be used here are the MPAA values like 'R' or 'PG-13'. When more than one value is passed, it is assumed to be an OR search.
companies
Useful if you'd like to find the movies from a particular studio. You can pass it more than one id which is expected to be comma separated. When more than one id is passed, it is assumed to be an OR search.
countries
If you'd like to limit your result set to movies from a particular country you can pass their 2 letter country code. You can pass more than one value and in this case make sure they are comma separated. When more than one id is passed, it is assumed to be an OR search.

In the event that you request a language that has not been translated, the data will default back to English. This can be checked with the 'translated' boolean element.

The default locale for certifications and release dates is US. The last_modified_at time is UTC.

Example Response


<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <opensearch:Query searchTerms=""/>
  <opensearch:totalResults>5</opensearch:totalResults>
  <movies>
    <movie>
      <score></score>
      <popularity>3</popularity>
      <translated>true</translated>
      <adult>false</adult>
      <language>en</language>
      <original_name>When The Sun Goes Down</original_name>
      <name>When The Sun Goes Down</name>
      <alternative_name></alternative_name>
      <type>movie</type>
      <id>29734</id>
      <imdb_id>tt1525907</imdb_id>
      <url>http://www.themoviedb.org/movie/29734</url>
      <votes>5</votes>
      <rating>9.8</rating>
      <certification></certification>
      <overview>No overview found.</overview>
      <released>2005-01-05</released>
      <images>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/01e/4bc97392017a3c57fe03501e/when-the-sun-goes-down-original.jpg" size="original" width="1000" height="1500" id="4bc97392017a3c57fe03501e"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/01e/4bc97392017a3c57fe03501e/when-the-sun-goes-down-mid.jpg" size="mid" width="500" height="750" id="4bc97392017a3c57fe03501e"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/01e/4bc97392017a3c57fe03501e/when-the-sun-goes-down-cover.jpg" size="cover" width="185" height="278" id="4bc97392017a3c57fe03501e"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/01e/4bc97392017a3c57fe03501e/when-the-sun-goes-down-thumb.jpg" size="thumb" width="92" height="138" id="4bc97392017a3c57fe03501e"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/01a/4bc97392017a3c57fe03501a/when-the-sun-goes-down-original.jpg" size="original" width="1280" height="720" id="4bc97392017a3c57fe03501a"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/01a/4bc97392017a3c57fe03501a/when-the-sun-goes-down-poster.jpg" size="poster" width="780" height="439" id="4bc97392017a3c57fe03501a"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/01a/4bc97392017a3c57fe03501a/when-the-sun-goes-down-thumb.jpg" size="thumb" width="300" height="169" id="4bc97392017a3c57fe03501a"/>
      </images>
      <version>6</version>
      <last_modified_at>2010-07-19 20:32:27</last_modified_at>
    </movie>
    <movie>
      <score></score>
      <popularity>3</popularity>
      <translated>true</translated>
      <adult>false</adult>
      <language>en</language>
      <original_name>The Last Emperor</original_name>
      <name>The Last Emperor</name>
      <alternative_name></alternative_name>
      <type>movie</type>
      <id>746</id>
      <imdb_id>tt0093389</imdb_id>
      <url>http://www.themoviedb.org/movie/746</url>
      <votes>5</votes>
      <rating>9.4</rating>
      <certification></certification>
      <overview>The Last Emeror is a monumental film about the life of the last emperor of the Chinese Quinn dynasty. Director Bertolucci illustrates the life of Pu-Yi who was crowned emperor at the age of two only to loose it at the age of five. The film won a total of nine Oscars in 1987.</overview>
      <released>1987-10-29</released>
      <images>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/21c/4bc90bc1017a3c57fe00421c/the-last-emperor-original.jpg" size="original" width="1000" height="1500" id="4bc90bc1017a3c57fe00421c"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/21c/4bc90bc1017a3c57fe00421c/the-last-emperor-mid.jpg" size="mid" width="500" height="750" id="4bc90bc1017a3c57fe00421c"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/21c/4bc90bc1017a3c57fe00421c/the-last-emperor-cover.jpg" size="cover" width="185" height="278" id="4bc90bc1017a3c57fe00421c"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/21c/4bc90bc1017a3c57fe00421c/the-last-emperor-thumb.jpg" size="thumb" width="92" height="138" id="4bc90bc1017a3c57fe00421c"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/213/4bc90bc0017a3c57fe004213/the-last-emperor-original.jpg" size="original" width="1280" height="720" id="4bc90bc0017a3c57fe004213"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/213/4bc90bc0017a3c57fe004213/the-last-emperor-poster.jpg" size="poster" width="780" height="439" id="4bc90bc0017a3c57fe004213"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/213/4bc90bc0017a3c57fe004213/the-last-emperor-thumb.jpg" size="thumb" width="300" height="169" id="4bc90bc0017a3c57fe004213"/>
      </images>
      <version>30</version>
      <last_modified_at>2010-07-26 09:15:39</last_modified_at>
    </movie>
    <movie>
      <score></score>
      <popularity>3</popularity>
      <translated>true</translated>
      <adult>false</adult>
      <language>en</language>
      <original_name>Das Verlangen</original_name>
      <name>Das Verlangen</name>
      <alternative_name></alternative_name>
      <type>movie</type>
      <id>6179</id>
      <imdb_id>tt0328727</imdb_id>
      <url>http://www.themoviedb.org/movie/6179</url>
      <votes>5</votes>
      <rating>9.2</rating>
      <certification></certification>
      <overview>No overview found.</overview>
      <released>2002-08-08</released>
      <images>
      </images>
      <version>18</version>
      <last_modified_at>2010-07-19 18:46:37</last_modified_at>
    </movie>
    <movie>
      <score></score>
      <popularity>3</popularity>
      <translated>true</translated>
      <adult>false</adult>
      <language>en</language>
      <original_name>Elephant</original_name>
      <name>Elephant</name>
      <alternative_name></alternative_name>
      <type>movie</type>
      <id>1807</id>
      <imdb_id>tt0363589</imdb_id>
      <url>http://www.themoviedb.org/movie/1807</url>
      <votes>5</votes>
      <rating>9.2</rating>
      <certification></certification>
      <overview>Elephant is a Gus Van Sant film depicting the story of a high school just before and after a massive shooting. The film is shot in a way that makes the viewer seem like they are there, in the high school, slowly walking around witnessing ever characters story unfold. The film won the Palme d&#8217;Or and Best Director at the 2003 Cannes Film Festival.</overview>
      <released>2003-05-18</released>
      <images>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/015/4c1f544a7b9aa13123000015/elephant-original.jpg" size="original" width="1000" height="1500" id="4c1f544a7b9aa13123000015"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/015/4c1f544a7b9aa13123000015/elephant-mid.jpg" size="mid" width="500" height="750" id="4c1f544a7b9aa13123000015"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/015/4c1f544a7b9aa13123000015/elephant-cover.jpg" size="cover" width="185" height="278" id="4c1f544a7b9aa13123000015"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/015/4c1f544a7b9aa13123000015/elephant-thumb.jpg" size="thumb" width="92" height="138" id="4c1f544a7b9aa13123000015"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/0e0/4bc912ef017a3c57fe0070e0/elephant-original.jpg" size="original" width="1280" height="720" id="4bc912ef017a3c57fe0070e0"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/0e0/4bc912ef017a3c57fe0070e0/elephant-poster.jpg" size="poster" width="780" height="439" id="4bc912ef017a3c57fe0070e0"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/0e0/4bc912ef017a3c57fe0070e0/elephant-thumb.jpg" size="thumb" width="300" height="169" id="4bc912ef017a3c57fe0070e0"/>
      </images>
      <version>19</version>
      <last_modified_at>2010-07-19 22:15:58</last_modified_at>
    </movie>
    <movie>
      <score></score>
      <popularity>3</popularity>
      <translated>true</translated>
      <adult>false</adult>
      <language>en</language>
      <original_name>Frida</original_name>
      <name>Frida</name>
      <alternative_name></alternative_name>
      <type>movie</type>
      <id>1360</id>
      <imdb_id>tt0120679</imdb_id>
      <url>http://www.themoviedb.org/movie/1360</url>
      <votes>5</votes>
      <rating>9.2</rating>
      <certification></certification>
      <overview>No overview found.</overview>
      <released>2002-08-29</released>
      <images>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/c40/4bc90feb017a3c57fe005c40/frida-original.jpg" size="original" width="1000" height="1428" id="4bc90feb017a3c57fe005c40"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/c40/4bc90feb017a3c57fe005c40/frida-mid.jpg" size="mid" width="500" height="714" id="4bc90feb017a3c57fe005c40"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/c40/4bc90feb017a3c57fe005c40/frida-cover.jpg" size="cover" width="185" height="264" id="4bc90feb017a3c57fe005c40"/>
        <image type="poster" url="http://hwcdn.themoviedb.org/posters/c40/4bc90feb017a3c57fe005c40/frida-thumb.jpg" size="thumb" width="92" height="131" id="4bc90feb017a3c57fe005c40"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/c3c/4bc90fea017a3c57fe005c3c/frida-original.jpg" size="original" width="1280" height="720" id="4bc90fea017a3c57fe005c3c"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/c3c/4bc90fea017a3c57fe005c3c/frida-poster.jpg" size="poster" width="780" height="439" id="4bc90fea017a3c57fe005c3c"/>
        <image type="backdrop" url="http://hwcdn.themoviedb.org/backdrops/c3c/4bc90fea017a3c57fe005c3c/frida-thumb.jpg" size="thumb" width="300" height="169" id="4bc90fea017a3c57fe005c3c"/>
      </images>
      <version>34</version>
      <last_modified_at>2010-07-19 23:54:18</last_modified_at>
    </movie>
  </movies>
</OpenSearchDescription>

themoviedb.org is a free and open movie database. It's completely user driven by people like you. TMDb is currently used by millions of people every month and with our powerful API, also used by the world's most popular media centers.

Overview

API Methods

Movie.browse

Example URL

Options

Example Response