# TMDB

> Search The Movie Database for films and TV shows, pull a title's full record and its cast and crew, and read what's trending.

App · Film, TV & Fandom · 5 actions. Web page: https://docs.lodol.com/docs/integrations/tmdb

## Actions

### Get film cast and crew

List the cast and crew credited on a film.

**Inputs**

- Film ID (`movie_id`, text, required): The film's TMDB ID, as returned by Search films or What's trending.

**Outputs**

- `cast` (list): The credited cast, in billing order
- `crew` (list): The credited crew
- `tmdb_id` (number): The film's TMDB ID

**Example output**

```json
{
  "cast": [
    {
      "character": "Dom Cobb",
      "name": "Leonardo DiCaprio",
      "order": 0,
      "person_id": 6193,
      "profile_url": "https://image.tmdb.org/t/p/w185/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg"
    }
  ],
  "crew": [
    {
      "department": "Directing",
      "job": "Director",
      "name": "Christopher Nolan",
      "person_id": 525,
      "profile_url": "https://image.tmdb.org/t/p/w185/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg"
    }
  ],
  "tmdb_id": 27205
}
```

### Get film details

Look up one film's full record: runtime, genres, budget, revenue, tagline, and its IMDb ID.

**Inputs**

- Film ID (`movie_id`, text, required): The film's TMDB ID, as returned by Search films or What's trending.
- Language (`language`, text): Optional. Return titles and summaries in this language, for example 'en-US' or 'fr-FR'. Defaults to English.

**Outputs**

- `backdrop_url` (text): Direct link to the wide backdrop image, ready to use
- `budget` (number): Production budget in US dollars, or 0 if unknown
- `genres` (list): Genre names, for example 'Science Fiction'
- `homepage` (text): The film's official website
- `imdb_id` (text): The film's IMDb ID, for example 'tt1375666'
- `media_type` (text): Whether this is a 'movie', a 'tv' show, or a 'person'
- `original_language` (text): Two-letter code for the original language, for example 'en'
- `original_title` (text): The title in its original language
- `overview` (text): A short plot summary
- `popularity` (number): TMDB's popularity score
- `poster_url` (text): Direct link to the poster image, ready to use
- `production_companies` (list): Names of the companies that produced it
- `release_date` (text): When it came out, as YYYY-MM-DD. For TV this is the first air date.
- `release_status` (text): Where the film is in production, for example 'Released', 'Post Production', or 'Planned'
- `revenue` (number): Box office takings in US dollars, or 0 if unknown
- `runtime` (number): How long the film runs, in minutes
- `tagline` (text): The film's tagline, if it has one
- `title` (text): The title. TMDB calls this 'title' for films and 'name' for TV, so both are read into this one field.
- `tmdb_id` (number): The title's TMDB ID. Use with the film detail actions.
- `vote_average` (number): Average user rating out of 10
- `vote_count` (number): How many users have rated it

**Example output**

```json
{
  "backdrop_url": "https://image.tmdb.org/t/p/w1280/s3TBrRGB1iav7gFOCNx3H31MoES.jpg",
  "budget": 160000000,
  "genres": [
    "Action",
    "Science Fiction",
    "Adventure"
  ],
  "homepage": "https://www.warnerbros.com/movies/inception",
  "imdb_id": "tt1375666",
  "media_type": "movie",
  "original_language": "en",
  "original_title": "Inception",
  "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets, is offered a chance to regain his old life as payment for a task no one thinks is possible.",
  "popularity": 84.2,
  "poster_url": "https://image.tmdb.org/t/p/w500/oYuLEt3zVCKq57qu2F8dT7NIa6f.jpg",
  "production_companies": [
    "Legendary Pictures",
    "Syncopy"
  ],
  "release_date": "2010-07-15",
  "release_status": "Released",
  "revenue": 825532764,
  "runtime": 148,
  "tagline": "Your mind is the scene of the crime.",
  "title": "Inception",
  "tmdb_id": 27205,
  "vote_average": 8.4,
  "vote_count": 36547
}
```

### Get what's trending

List the films and TV shows trending on TMDB today or over the past week.

**Inputs**

- What to include (`media_type`, text): Which kind of trending list to read. One of: `all` (Films and TV), `movie` (Films only), `tv` (TV only), `person` (People only). Default: `all`.
- Over what period (`time_window`, text): Trending today, or trending over the past week. One of: `day` (Today), `week` (This week). Default: `day`.
- Language (`language`, text): Optional. Return titles and summaries in this language, for example 'en-US' or 'fr-FR'. Defaults to English.

**Outputs**

- `media_type` (text): Which trending list this is
- `page` (number): The page of results this is
- `results` (list): The trending titles, most popular first. Read each row's media_type to tell films from TV shows.
- `time_window` (text): Whether this covers 'day' or 'week'
- `total_pages` (number): How many pages there are
- `total_results` (number): How many results match in total

**Example output**

```json
{
  "media_type": "all",
  "page": 1,
  "results": [
    {
      "backdrop_url": "https://image.tmdb.org/t/p/w1280/s3TBrRGB1iav7gFOCNx3H31MoES.jpg",
      "media_type": "movie",
      "original_language": "en",
      "original_title": "Inception",
      "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets, is offered a chance to regain his old life as payment for a task no one thinks is possible.",
      "popularity": 84.2,
      "poster_url": "https://image.tmdb.org/t/p/w500/oYuLEt3zVCKq57qu2F8dT7NIa6f.jpg",
      "release_date": "2010-07-15",
      "title": "Inception",
      "tmdb_id": 27205,
      "vote_average": 8.4,
      "vote_count": 36547
    }
  ],
  "time_window": "day",
  "total_pages": 1000,
  "total_results": 20000
}
```

### Search films

Search The Movie Database for films by title.

**Inputs**

- Title (`query`, text, required): The film title to search for, for example 'Inception'.
- Release year (`year`, text): Optional. Only return films released in this year, for example '2010'.
- Language (`language`, text): Optional. Return titles and summaries in this language, for example 'en-US' or 'fr-FR'. Defaults to English.
- Include adult titles (`include_adult`, true/false): Include adult titles in the results. Off by default. Default: `false`.
- Page (`page`, number): Which page of results to return (1-500). From 1 to 500. Default: `1`.

**Outputs**

- `page` (number): The page of results this is
- `results` (list): The matching films, most relevant first
- `total_pages` (number): How many pages there are
- `total_results` (number): How many results match in total

**Example output**

```json
{
  "page": 1,
  "results": [
    {
      "backdrop_url": "https://image.tmdb.org/t/p/w1280/s3TBrRGB1iav7gFOCNx3H31MoES.jpg",
      "media_type": "movie",
      "original_language": "en",
      "original_title": "Inception",
      "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets, is offered a chance to regain his old life as payment for a task no one thinks is possible.",
      "popularity": 84.2,
      "poster_url": "https://image.tmdb.org/t/p/w500/oYuLEt3zVCKq57qu2F8dT7NIa6f.jpg",
      "release_date": "2010-07-15",
      "title": "Inception",
      "tmdb_id": 27205,
      "vote_average": 8.4,
      "vote_count": 36547
    }
  ],
  "total_pages": 2,
  "total_results": 24
}
```

### Search TV shows

Search The Movie Database for television shows by title.

**Inputs**

- Title (`query`, text, required): The show title to search for, for example 'Breaking Bad'.
- First aired in (`first_air_date_year`, text): Optional. Only return shows that first aired in this year, for example '2008'.
- Language (`language`, text): Optional. Return titles and summaries in this language, for example 'en-US' or 'fr-FR'. Defaults to English.
- Include adult titles (`include_adult`, true/false): Include adult titles in the results. Off by default. Default: `false`.
- Page (`page`, number): Which page of results to return (1-500). From 1 to 500. Default: `1`.

**Outputs**

- `page` (number): The page of results this is
- `results` (list): The matching shows, most relevant first
- `total_pages` (number): How many pages there are
- `total_results` (number): How many results match in total

**Example output**

```json
{
  "page": 1,
  "results": [
    {
      "backdrop_url": "https://image.tmdb.org/t/p/w1280/s3TBrRGB1iav7gFOCNx3H31MoES.jpg",
      "media_type": "tv",
      "original_language": "en",
      "original_title": "Breaking Bad",
      "overview": "A high school chemistry teacher diagnosed with terminal lung cancer turns to manufacturing and selling methamphetamine to secure his family's future.",
      "popularity": 84.2,
      "poster_url": "https://image.tmdb.org/t/p/w500/oYuLEt3zVCKq57qu2F8dT7NIa6f.jpg",
      "release_date": "2008-01-20",
      "title": "Breaking Bad",
      "tmdb_id": 1396,
      "vote_average": 8.9,
      "vote_count": 14203
    }
  ],
  "total_pages": 1,
  "total_results": 3
}
```