# OMDb

> Look up films, series and episodes on the Open Movie Database: plot, cast, genres, runtime, awards, posters and IMDb, Rotten Tomatoes and Metacritic scores.

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

## Actions

### Get cast and crew

Read who directed, wrote and starred in a title, each as a list rather than one comma-joined string. Identify the title by IMDb ID or by name. OMDb credits the headline names only, not the full cast.

**Inputs**

- IMDb ID (`imdb_id`, text): The title's IMDb ID, for example 'tt1375666'. Fill in either this or the title. An IMDb ID is exact, so prefer it when an earlier step produced one.
- Title (`title`, text): The title's name, for example 'Inception'. Fill in either this or the IMDb ID. OMDb matches one title by name, so add a year if the name is shared.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.

**Outputs**

- `actors` (list)
- `credit_count` (number): How many names OMDb credited across all three lists
- `directors` (list)
- `imdb_id` (text): The title's IMDb ID, for example 'tt1375666'. Use it to look the title up again without re-searching.
- `imdb_url` (text): Link to the title's page on imdb.com. Built from the IMDb ID - OMDb does not send it.
- `title` (text): The title's name
- `writers` (list)
- `year` (text): The year as OMDb writes it: '2010' for a film, '2008-2013' for a finished series, '2016-' for one still running.

**Example output**

```json
{
  "actors": [
    "Leonardo DiCaprio",
    "Joseph Gordon-Levitt",
    "Elliot Page"
  ],
  "credit_count": 5,
  "directors": [
    "Christopher Nolan"
  ],
  "imdb_id": "tt1375666",
  "imdb_url": "https://www.imdb.com/title/tt1375666/",
  "title": "Inception",
  "writers": [
    "Christopher Nolan"
  ],
  "year": "2010"
}
```

### Get episode

Look up one episode of a series by season and episode number, and return its full record. Name the series either by title or by its IMDb ID.

**Inputs**

- Series title (`series_title`, text): The series' name, for example 'Game of Thrones'. Fill in either this or the series' IMDb ID.
- Series IMDb ID (`series_imdb_id`, text): The series' IMDb ID, for example 'tt0944947'. Fill in either this or the series title. This is the series' ID, not an episode's.
- Season (`season`, number, required): Which season, counting from 1. From 1 to 1000.
- Episode (`episode`, number, required): Which episode within that season, counting from 1. From 1 to 10000.
- Plot length (`plot`, text): How much of the plot to return. 'Short' is a one-line summary; 'full' is the complete synopsis. Defaults to short. One of: `short` (Short - a one-line summary), `full` (Full - the complete synopsis). Default: `short`.

**Outputs**

- `actors` (list)
- `awards` (text): A summary of awards and nominations
- `box_office` (number): Box office takings in US dollars, as a number
- `box_office_text` (text): Box office takings as OMDb writes them
- `countries` (list)
- `directors` (list)
- `dvd_release` (text): Home release date as YYYY-MM-DD, when OMDb has one
- `episode` (number): The episode's number within its season. Null for films and series.
- `genres` (list)
- `imdb_id` (text): The title's IMDb ID, for example 'tt1375666'. Use it to look the title up again without re-searching.
- `imdb_rating` (number): IMDb's average score out of 10
- `imdb_url` (text): Link to the title's page on imdb.com. Built from the IMDb ID - OMDb does not send it.
- `imdb_votes` (number): How many IMDb users have rated it
- `languages` (list)
- `metascore` (number): The Metacritic score out of 100
- `plot` (text): Plot summary. Short by default; ask for the full one with 'plot'.
- `poster_url` (text): Direct link to the poster image. Null when OMDb has no artwork.
- `production` (text): The production company, when OMDb has one
- `rated` (text): Age certificate, for example 'PG-13'
- `ratings` (list)
- `released` (text): The release date as YYYY-MM-DD, ready for a date field
- `released_text` (text): The release date as OMDb writes it, '16 Jul 2010'
- `runtime_minutes` (number): Running time in minutes, as a number
- `runtime_text` (text): Running time as OMDb writes it, '148 min'
- `season` (number): Which season an episode belongs to. Null for films and series.
- `series_imdb_id` (text): The IMDb ID of an episode's parent series. Null for films and series.
- `still_running` (true/false): True for a series OMDb shows no end year for
- `title` (text): The title's name
- `total_seasons` (number): How many seasons a series ran for. Null for films and episodes.
- `type` (text): What kind of title this is: 'movie', 'series' or 'episode'
- `website` (text): The title's official site, when OMDb has one
- `writers` (list)
- `year` (text): The year as OMDb writes it: '2010' for a film, '2008-2013' for a finished series, '2016-' for one still running.
- `year_end` (number): A series' last year. Null while it is still running.
- `year_start` (number): The year it came out, or a series' first year

**Example output**

```json
{
  "actors": [
    "Sean Bean",
    "Mark Addy",
    "Nikolaj Coster-Waldau"
  ],
  "awards": "1 win & 1 nomination",
  "box_office": null,
  "box_office_text": "",
  "countries": [
    "United States"
  ],
  "directors": [
    "Timothy Van Patten"
  ],
  "dvd_release": null,
  "episode": 1,
  "genres": [
    "Action",
    "Adventure",
    "Drama"
  ],
  "imdb_id": "tt1480055",
  "imdb_rating": 9.1,
  "imdb_url": "https://www.imdb.com/title/tt1480055/",
  "imdb_votes": 59423,
  "languages": [
    "English"
  ],
  "metascore": null,
  "plot": "Eddard Stark is torn between his family and an old friend when asked to serve at the side of King Robert Baratheon.",
  "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
  "production": null,
  "rated": "TV-MA",
  "ratings": [
    {
      "out_of": 10.0,
      "percent": 91.0,
      "score": 9.1,
      "source": "Internet Movie Database",
      "value": "9.1/10"
    }
  ],
  "released": "2011-04-17",
  "released_text": "17 Apr 2011",
  "runtime_minutes": 62,
  "runtime_text": "62 min",
  "season": 1,
  "series_imdb_id": "tt0944947",
  "still_running": false,
  "title": "Winter Is Coming",
  "total_seasons": null,
  "type": "episode",
  "website": null,
  "writers": [
    "David Benioff",
    "D.B. Weiss",
    "George R.R. Martin"
  ],
  "year": "2011",
  "year_end": 2011,
  "year_start": 2011
}
```

### Get film

Look up one film by title and return its full record, including box office and Rotten Tomatoes and Metacritic scores. Series of the same name are ignored.

**Inputs**

- Film title (`title`, text, required): The film to look up, for example 'Inception'.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.
- Plot length (`plot`, text): How much of the plot to return. 'Short' is a one-line summary; 'full' is the complete synopsis. Defaults to short. One of: `short` (Short - a one-line summary), `full` (Full - the complete synopsis). Default: `short`.

**Outputs**

- `actors` (list)
- `awards` (text): A summary of awards and nominations
- `box_office` (number): Box office takings in US dollars, as a number
- `box_office_text` (text): Box office takings as OMDb writes them
- `countries` (list)
- `directors` (list)
- `dvd_release` (text): Home release date as YYYY-MM-DD, when OMDb has one
- `episode` (number): The episode's number within its season. Null for films and series.
- `genres` (list)
- `imdb_id` (text): The title's IMDb ID, for example 'tt1375666'. Use it to look the title up again without re-searching.
- `imdb_rating` (number): IMDb's average score out of 10
- `imdb_url` (text): Link to the title's page on imdb.com. Built from the IMDb ID - OMDb does not send it.
- `imdb_votes` (number): How many IMDb users have rated it
- `languages` (list)
- `metascore` (number): The Metacritic score out of 100
- `plot` (text): Plot summary. Short by default; ask for the full one with 'plot'.
- `poster_url` (text): Direct link to the poster image. Null when OMDb has no artwork.
- `production` (text): The production company, when OMDb has one
- `rated` (text): Age certificate, for example 'PG-13'
- `ratings` (list)
- `released` (text): The release date as YYYY-MM-DD, ready for a date field
- `released_text` (text): The release date as OMDb writes it, '16 Jul 2010'
- `runtime_minutes` (number): Running time in minutes, as a number
- `runtime_text` (text): Running time as OMDb writes it, '148 min'
- `season` (number): Which season an episode belongs to. Null for films and series.
- `series_imdb_id` (text): The IMDb ID of an episode's parent series. Null for films and series.
- `still_running` (true/false): True for a series OMDb shows no end year for
- `title` (text): The title's name
- `total_seasons` (number): How many seasons a series ran for. Null for films and episodes.
- `type` (text): What kind of title this is: 'movie', 'series' or 'episode'
- `website` (text): The title's official site, when OMDb has one
- `writers` (list)
- `year` (text): The year as OMDb writes it: '2010' for a film, '2008-2013' for a finished series, '2016-' for one still running.
- `year_end` (number): A series' last year. Null while it is still running.
- `year_start` (number): The year it came out, or a series' first year

**Example output**

```json
{
  "actors": [
    "Leonardo DiCaprio",
    "Joseph Gordon-Levitt",
    "Elliot Page"
  ],
  "awards": "Won 4 Oscars. 159 wins & 220 nominations total",
  "box_office": 292587330,
  "box_office_text": "$292,587,330",
  "countries": [
    "United States",
    "United Kingdom"
  ],
  "directors": [
    "Christopher Nolan"
  ],
  "dvd_release": null,
  "episode": null,
  "genres": [
    "Action",
    "Adventure",
    "Sci-Fi"
  ],
  "imdb_id": "tt1375666",
  "imdb_rating": 8.8,
  "imdb_url": "https://www.imdb.com/title/tt1375666/",
  "imdb_votes": 2548132,
  "languages": [
    "English",
    "Japanese",
    "French"
  ],
  "metascore": 74,
  "plot": "A thief who steals corporate secrets through the use of dream-sharing technology is given the inverse task of planting an idea into the mind of a C.E.O.",
  "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
  "production": null,
  "rated": "PG-13",
  "ratings": [
    {
      "out_of": 10.0,
      "percent": 88.0,
      "score": 8.8,
      "source": "Internet Movie Database",
      "value": "8.8/10"
    },
    {
      "out_of": 100.0,
      "percent": 87.0,
      "score": 87.0,
      "source": "Rotten Tomatoes",
      "value": "87%"
    },
    {
      "out_of": 100.0,
      "percent": 74.0,
      "score": 74.0,
      "source": "Metacritic",
      "value": "74/100"
    }
  ],
  "released": "2010-07-16",
  "released_text": "16 Jul 2010",
  "runtime_minutes": 148,
  "runtime_text": "148 min",
  "season": null,
  "series_imdb_id": null,
  "still_running": false,
  "title": "Inception",
  "total_seasons": null,
  "type": "movie",
  "website": null,
  "writers": [
    "Christopher Nolan"
  ],
  "year": "2010",
  "year_end": 2010,
  "year_start": 2010
}
```

### Get plot

Read a title's plot summary, short or full, with its genres, age rating and runtime. Identify the title by IMDb ID or by name.

**Inputs**

- IMDb ID (`imdb_id`, text): The title's IMDb ID, for example 'tt1375666'. Fill in either this or the title. An IMDb ID is exact, so prefer it when an earlier step produced one.
- Title (`title`, text): The title's name, for example 'Inception'. Fill in either this or the IMDb ID. OMDb matches one title by name, so add a year if the name is shared.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.
- Plot length (`plot`, text): How much of the plot to return. 'Short' is a one-line summary; 'full' is the complete synopsis. Defaults to short. One of: `short` (Short - a one-line summary), `full` (Full - the complete synopsis). Default: `short`.

**Outputs**

- `genres` (list)
- `imdb_id` (text): The title's IMDb ID, for example 'tt1375666'. Use it to look the title up again without re-searching.
- `imdb_url` (text): Link to the title's page on imdb.com. Built from the IMDb ID - OMDb does not send it.
- `plot` (text): The plot summary
- `plot_length` (text): Which version was asked for: 'short' or 'full'
- `rated` (text): Age certificate, for example 'PG-13'
- `runtime_minutes` (number): Running time in minutes
- `title` (text): The title's name
- `year` (text): The year as OMDb writes it: '2010' for a film, '2008-2013' for a finished series, '2016-' for one still running.

**Example output**

```json
{
  "genres": [
    "Action",
    "Adventure",
    "Sci-Fi"
  ],
  "imdb_id": "tt1375666",
  "imdb_url": "https://www.imdb.com/title/tt1375666/",
  "plot": "A thief who steals corporate secrets through the use of dream-sharing technology is given the inverse task of planting an idea into the mind of a C.E.O.",
  "plot_length": "short",
  "rated": "PG-13",
  "runtime_minutes": 148,
  "title": "Inception",
  "year": "2010"
}
```

### Get poster URL

Read the poster image URL for a title, ready to attach to an email or a message. Identify the title by IMDb ID or by name. 'has_poster' is false when OMDb holds no artwork for it.

**Inputs**

- IMDb ID (`imdb_id`, text): The title's IMDb ID, for example 'tt1375666'. Fill in either this or the title. An IMDb ID is exact, so prefer it when an earlier step produced one.
- Title (`title`, text): The title's name, for example 'Inception'. Fill in either this or the IMDb ID. OMDb matches one title by name, so add a year if the name is shared.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.

**Outputs**

- `has_poster` (true/false): Whether OMDb had a poster at all
- `imdb_id` (text): The title's IMDb ID, for example 'tt1375666'. Use it to look the title up again without re-searching.
- `imdb_url` (text): Link to the title's page on imdb.com. Built from the IMDb ID - OMDb does not send it.
- `poster_url` (text): Direct link to the poster image. Null when OMDb has no artwork for this title.
- `title` (text): The title's name
- `year` (text): The year as OMDb writes it: '2010' for a film, '2008-2013' for a finished series, '2016-' for one still running.

**Example output**

```json
{
  "has_poster": true,
  "imdb_id": "tt1375666",
  "imdb_url": "https://www.imdb.com/title/tt1375666/",
  "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
  "title": "Inception",
  "year": "2010"
}
```

### Get ratings

Read every score a title carries - IMDb, Rotten Tomatoes and Metacritic - with each one converted to a percentage so they can be compared, plus their average. Identify the title by IMDb ID or by name.

**Inputs**

- IMDb ID (`imdb_id`, text): The title's IMDb ID, for example 'tt1375666'. Fill in either this or the title. An IMDb ID is exact, so prefer it when an earlier step produced one.
- Title (`title`, text): The title's name, for example 'Inception'. Fill in either this or the IMDb ID. OMDb matches one title by name, so add a year if the name is shared.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.

**Outputs**

- `average_percent` (number): The mean of every source's score as a percentage. Null when no source reported a parseable score.
- `imdb_id` (text): The title's IMDb ID, for example 'tt1375666'. Use it to look the title up again without re-searching.
- `imdb_rating` (number): IMDb's average score out of 10
- `imdb_url` (text): Link to the title's page on imdb.com. Built from the IMDb ID - OMDb does not send it.
- `imdb_votes` (number): How many IMDb users have rated it
- `metascore` (number): The Metacritic score out of 100
- `rating_count` (number): How many sources scored it
- `ratings` (list): Every source that scored this title
- `title` (text): The title's name
- `year` (text): The year as OMDb writes it: '2010' for a film, '2008-2013' for a finished series, '2016-' for one still running.

**Example output**

```json
{
  "average_percent": 83.0,
  "imdb_id": "tt1375666",
  "imdb_rating": 8.8,
  "imdb_url": "https://www.imdb.com/title/tt1375666/",
  "imdb_votes": 2548132,
  "metascore": 74,
  "rating_count": 3,
  "ratings": [
    {
      "out_of": 10.0,
      "percent": 88.0,
      "score": 8.8,
      "source": "Internet Movie Database",
      "value": "8.8/10"
    },
    {
      "out_of": 100.0,
      "percent": 87.0,
      "score": 87.0,
      "source": "Rotten Tomatoes",
      "value": "87%"
    },
    {
      "out_of": 100.0,
      "percent": 74.0,
      "score": 74.0,
      "source": "Metacritic",
      "value": "74/100"
    }
  ],
  "title": "Inception",
  "year": "2010"
}
```

### Get series

Look up one TV series by title and return its full record, including how many seasons it ran for and whether it is still running. Films of the same name are ignored.

**Inputs**

- Series title (`title`, text, required): The series to look up, for example 'Game of Thrones'.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.
- Plot length (`plot`, text): How much of the plot to return. 'Short' is a one-line summary; 'full' is the complete synopsis. Defaults to short. One of: `short` (Short - a one-line summary), `full` (Full - the complete synopsis). Default: `short`.

**Outputs**

- `actors` (list)
- `awards` (text): A summary of awards and nominations
- `box_office` (number): Box office takings in US dollars, as a number
- `box_office_text` (text): Box office takings as OMDb writes them
- `countries` (list)
- `directors` (list)
- `dvd_release` (text): Home release date as YYYY-MM-DD, when OMDb has one
- `episode` (number): The episode's number within its season. Null for films and series.
- `genres` (list)
- `imdb_id` (text): The title's IMDb ID, for example 'tt1375666'. Use it to look the title up again without re-searching.
- `imdb_rating` (number): IMDb's average score out of 10
- `imdb_url` (text): Link to the title's page on imdb.com. Built from the IMDb ID - OMDb does not send it.
- `imdb_votes` (number): How many IMDb users have rated it
- `languages` (list)
- `metascore` (number): The Metacritic score out of 100
- `plot` (text): Plot summary. Short by default; ask for the full one with 'plot'.
- `poster_url` (text): Direct link to the poster image. Null when OMDb has no artwork.
- `production` (text): The production company, when OMDb has one
- `rated` (text): Age certificate, for example 'PG-13'
- `ratings` (list)
- `released` (text): The release date as YYYY-MM-DD, ready for a date field
- `released_text` (text): The release date as OMDb writes it, '16 Jul 2010'
- `runtime_minutes` (number): Running time in minutes, as a number
- `runtime_text` (text): Running time as OMDb writes it, '148 min'
- `season` (number): Which season an episode belongs to. Null for films and series.
- `series_imdb_id` (text): The IMDb ID of an episode's parent series. Null for films and series.
- `still_running` (true/false): True for a series OMDb shows no end year for
- `title` (text): The title's name
- `total_seasons` (number): How many seasons a series ran for. Null for films and episodes.
- `type` (text): What kind of title this is: 'movie', 'series' or 'episode'
- `website` (text): The title's official site, when OMDb has one
- `writers` (list)
- `year` (text): The year as OMDb writes it: '2010' for a film, '2008-2013' for a finished series, '2016-' for one still running.
- `year_end` (number): A series' last year. Null while it is still running.
- `year_start` (number): The year it came out, or a series' first year

**Example output**

```json
{
  "actors": [
    "Emilia Clarke",
    "Peter Dinklage",
    "Kit Harington"
  ],
  "awards": "Won 59 Primetime Emmys. 400 wins & 655 nominations total",
  "box_office": null,
  "box_office_text": "",
  "countries": [
    "United States",
    "United Kingdom"
  ],
  "directors": [],
  "dvd_release": null,
  "episode": null,
  "genres": [
    "Action",
    "Adventure",
    "Drama"
  ],
  "imdb_id": "tt0944947",
  "imdb_rating": 9.2,
  "imdb_url": "https://www.imdb.com/title/tt0944947/",
  "imdb_votes": 2371504,
  "languages": [
    "English"
  ],
  "metascore": null,
  "plot": "Nine noble families fight for control over the lands of Westeros, while an ancient enemy returns after being dormant for a millennia.",
  "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
  "production": null,
  "rated": "TV-MA",
  "ratings": [
    {
      "out_of": 10.0,
      "percent": 88.0,
      "score": 8.8,
      "source": "Internet Movie Database",
      "value": "8.8/10"
    }
  ],
  "released": "2011-04-17",
  "released_text": "17 Apr 2011",
  "runtime_minutes": 57,
  "runtime_text": "57 min",
  "season": null,
  "series_imdb_id": null,
  "still_running": false,
  "title": "Game of Thrones",
  "total_seasons": 8,
  "type": "series",
  "website": null,
  "writers": [
    "David Benioff",
    "D.B. Weiss"
  ],
  "year": "2011-2019",
  "year_end": 2019,
  "year_start": 2011
}
```

### Get title by IMDb ID

Look up one film, series or episode by its IMDb ID and return its full record: plot, cast, genres, runtime, ratings and poster. An IMDb ID is exact, so this is the reliable way to read a title an earlier step found.

**Inputs**

- IMDb ID (`imdb_id`, text, required): The title's IMDb ID, for example 'tt1375666'. A full imdb.com/title/ URL is accepted too, and the ID is read out of it.
- Plot length (`plot`, text): How much of the plot to return. 'Short' is a one-line summary; 'full' is the complete synopsis. Defaults to short. One of: `short` (Short - a one-line summary), `full` (Full - the complete synopsis). Default: `short`.

**Outputs**

- `actors` (list)
- `awards` (text): A summary of awards and nominations
- `box_office` (number): Box office takings in US dollars, as a number
- `box_office_text` (text): Box office takings as OMDb writes them
- `countries` (list)
- `directors` (list)
- `dvd_release` (text): Home release date as YYYY-MM-DD, when OMDb has one
- `episode` (number): The episode's number within its season. Null for films and series.
- `genres` (list)
- `imdb_id` (text): The title's IMDb ID, for example 'tt1375666'. Use it to look the title up again without re-searching.
- `imdb_rating` (number): IMDb's average score out of 10
- `imdb_url` (text): Link to the title's page on imdb.com. Built from the IMDb ID - OMDb does not send it.
- `imdb_votes` (number): How many IMDb users have rated it
- `languages` (list)
- `metascore` (number): The Metacritic score out of 100
- `plot` (text): Plot summary. Short by default; ask for the full one with 'plot'.
- `poster_url` (text): Direct link to the poster image. Null when OMDb has no artwork.
- `production` (text): The production company, when OMDb has one
- `rated` (text): Age certificate, for example 'PG-13'
- `ratings` (list)
- `released` (text): The release date as YYYY-MM-DD, ready for a date field
- `released_text` (text): The release date as OMDb writes it, '16 Jul 2010'
- `runtime_minutes` (number): Running time in minutes, as a number
- `runtime_text` (text): Running time as OMDb writes it, '148 min'
- `season` (number): Which season an episode belongs to. Null for films and series.
- `series_imdb_id` (text): The IMDb ID of an episode's parent series. Null for films and series.
- `still_running` (true/false): True for a series OMDb shows no end year for
- `title` (text): The title's name
- `total_seasons` (number): How many seasons a series ran for. Null for films and episodes.
- `type` (text): What kind of title this is: 'movie', 'series' or 'episode'
- `website` (text): The title's official site, when OMDb has one
- `writers` (list)
- `year` (text): The year as OMDb writes it: '2010' for a film, '2008-2013' for a finished series, '2016-' for one still running.
- `year_end` (number): A series' last year. Null while it is still running.
- `year_start` (number): The year it came out, or a series' first year

**Example output**

```json
{
  "actors": [
    "Leonardo DiCaprio",
    "Joseph Gordon-Levitt",
    "Elliot Page"
  ],
  "awards": "Won 4 Oscars. 159 wins & 220 nominations total",
  "box_office": 292587330,
  "box_office_text": "$292,587,330",
  "countries": [
    "United States",
    "United Kingdom"
  ],
  "directors": [
    "Christopher Nolan"
  ],
  "dvd_release": null,
  "episode": null,
  "genres": [
    "Action",
    "Adventure",
    "Sci-Fi"
  ],
  "imdb_id": "tt1375666",
  "imdb_rating": 8.8,
  "imdb_url": "https://www.imdb.com/title/tt1375666/",
  "imdb_votes": 2548132,
  "languages": [
    "English",
    "Japanese",
    "French"
  ],
  "metascore": 74,
  "plot": "A thief who steals corporate secrets through the use of dream-sharing technology is given the inverse task of planting an idea into the mind of a C.E.O.",
  "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
  "production": null,
  "rated": "PG-13",
  "ratings": [
    {
      "out_of": 10.0,
      "percent": 88.0,
      "score": 8.8,
      "source": "Internet Movie Database",
      "value": "8.8/10"
    },
    {
      "out_of": 100.0,
      "percent": 87.0,
      "score": 87.0,
      "source": "Rotten Tomatoes",
      "value": "87%"
    },
    {
      "out_of": 100.0,
      "percent": 74.0,
      "score": 74.0,
      "source": "Metacritic",
      "value": "74/100"
    }
  ],
  "released": "2010-07-16",
  "released_text": "16 Jul 2010",
  "runtime_minutes": 148,
  "runtime_text": "148 min",
  "season": null,
  "series_imdb_id": null,
  "still_running": false,
  "title": "Inception",
  "total_seasons": null,
  "type": "movie",
  "website": null,
  "writers": [
    "Christopher Nolan"
  ],
  "year": "2010",
  "year_end": 2010,
  "year_start": 2010
}
```

### Get title by name

Look up one film, series or episode by name and return its full record. Narrow it with a type or a year when the name is shared - OMDb returns a single best match, not a list.

**Inputs**

- Title (`title`, text, required): The title to look up, for example 'Inception'.
- Type (`type`, text): Optional. Only match this kind of title. Leave empty to let OMDb pick the best match of any kind. One of: `movie` (Film), `series`, `episode`.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.
- Plot length (`plot`, text): How much of the plot to return. 'Short' is a one-line summary; 'full' is the complete synopsis. Defaults to short. One of: `short` (Short - a one-line summary), `full` (Full - the complete synopsis). Default: `short`.

**Outputs**

- `actors` (list)
- `awards` (text): A summary of awards and nominations
- `box_office` (number): Box office takings in US dollars, as a number
- `box_office_text` (text): Box office takings as OMDb writes them
- `countries` (list)
- `directors` (list)
- `dvd_release` (text): Home release date as YYYY-MM-DD, when OMDb has one
- `episode` (number): The episode's number within its season. Null for films and series.
- `genres` (list)
- `imdb_id` (text): The title's IMDb ID, for example 'tt1375666'. Use it to look the title up again without re-searching.
- `imdb_rating` (number): IMDb's average score out of 10
- `imdb_url` (text): Link to the title's page on imdb.com. Built from the IMDb ID - OMDb does not send it.
- `imdb_votes` (number): How many IMDb users have rated it
- `languages` (list)
- `metascore` (number): The Metacritic score out of 100
- `plot` (text): Plot summary. Short by default; ask for the full one with 'plot'.
- `poster_url` (text): Direct link to the poster image. Null when OMDb has no artwork.
- `production` (text): The production company, when OMDb has one
- `rated` (text): Age certificate, for example 'PG-13'
- `ratings` (list)
- `released` (text): The release date as YYYY-MM-DD, ready for a date field
- `released_text` (text): The release date as OMDb writes it, '16 Jul 2010'
- `runtime_minutes` (number): Running time in minutes, as a number
- `runtime_text` (text): Running time as OMDb writes it, '148 min'
- `season` (number): Which season an episode belongs to. Null for films and series.
- `series_imdb_id` (text): The IMDb ID of an episode's parent series. Null for films and series.
- `still_running` (true/false): True for a series OMDb shows no end year for
- `title` (text): The title's name
- `total_seasons` (number): How many seasons a series ran for. Null for films and episodes.
- `type` (text): What kind of title this is: 'movie', 'series' or 'episode'
- `website` (text): The title's official site, when OMDb has one
- `writers` (list)
- `year` (text): The year as OMDb writes it: '2010' for a film, '2008-2013' for a finished series, '2016-' for one still running.
- `year_end` (number): A series' last year. Null while it is still running.
- `year_start` (number): The year it came out, or a series' first year

**Example output**

```json
{
  "actors": [
    "Leonardo DiCaprio",
    "Joseph Gordon-Levitt",
    "Elliot Page"
  ],
  "awards": "Won 4 Oscars. 159 wins & 220 nominations total",
  "box_office": 292587330,
  "box_office_text": "$292,587,330",
  "countries": [
    "United States",
    "United Kingdom"
  ],
  "directors": [
    "Christopher Nolan"
  ],
  "dvd_release": null,
  "episode": null,
  "genres": [
    "Action",
    "Adventure",
    "Sci-Fi"
  ],
  "imdb_id": "tt1375666",
  "imdb_rating": 8.8,
  "imdb_url": "https://www.imdb.com/title/tt1375666/",
  "imdb_votes": 2548132,
  "languages": [
    "English",
    "Japanese",
    "French"
  ],
  "metascore": 74,
  "plot": "A thief who steals corporate secrets through the use of dream-sharing technology is given the inverse task of planting an idea into the mind of a C.E.O.",
  "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
  "production": null,
  "rated": "PG-13",
  "ratings": [
    {
      "out_of": 10.0,
      "percent": 88.0,
      "score": 8.8,
      "source": "Internet Movie Database",
      "value": "8.8/10"
    },
    {
      "out_of": 100.0,
      "percent": 87.0,
      "score": 87.0,
      "source": "Rotten Tomatoes",
      "value": "87%"
    },
    {
      "out_of": 100.0,
      "percent": 74.0,
      "score": 74.0,
      "source": "Metacritic",
      "value": "74/100"
    }
  ],
  "released": "2010-07-16",
  "released_text": "16 Jul 2010",
  "runtime_minutes": 148,
  "runtime_text": "148 min",
  "season": null,
  "series_imdb_id": null,
  "still_running": false,
  "title": "Inception",
  "total_seasons": null,
  "type": "movie",
  "website": null,
  "writers": [
    "Christopher Nolan"
  ],
  "year": "2010",
  "year_end": 2010,
  "year_start": 2010
}
```

### List season episodes

List every episode in one season of a series, with each episode's air date, IMDb rating and IMDb ID. Name the series either by title or by its IMDb ID.

**Inputs**

- Series title (`series_title`, text): The series' name, for example 'Game of Thrones'. Fill in either this or the series' IMDb ID.
- Series IMDb ID (`series_imdb_id`, text): The series' IMDb ID, for example 'tt0944947'. Fill in either this or the series title. This is the series' ID, not an episode's.
- Season (`season`, number, required): Which season, counting from 1. From 1 to 1000.

**Outputs**

- `episode_count` (number): How many episodes the season has
- `episodes` (list): The season's episodes, in broadcast order
- `season` (number): Which season this is
- `series_title` (text): The series this season belongs to
- `total_seasons` (number): How many seasons the series ran for in total

**Example output**

```json
{
  "episode_count": 2,
  "episodes": [
    {
      "episode": 1,
      "imdb_id": "tt1480055",
      "imdb_rating": 9.1,
      "imdb_url": "https://www.imdb.com/title/tt1480055/",
      "released": "2011-04-17",
      "released_text": "17 Apr 2011",
      "title": "Winter Is Coming"
    },
    {
      "episode": 2,
      "imdb_id": "tt1668746",
      "imdb_rating": 8.8,
      "imdb_url": "https://www.imdb.com/title/tt1668746/",
      "released": "2011-04-24",
      "released_text": "24 Apr 2011",
      "title": "The Kingsroad"
    }
  ],
  "season": 1,
  "series_title": "Game of Thrones",
  "total_seasons": 8
}
```

### Search episodes

Search OMDb for individual episodes by title and return a page of matches. Films and series are left out. A search that matches nothing returns no rows rather than failing.

**Inputs**

- Search for (`query`, text, required): The title to search for. OMDb refuses a term that matches too many titles, so prefer a distinctive one over a single common word.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.
- Page (`page`, number): Which page of results to return. OMDb serves ten per page and accepts pages 1-100, so the deepest result it will reach is the 1,000th. From 1 to 100. Default: `1`.

**Outputs**

- `has_more` (true/false): Whether another page can be fetched. False on the last page and on page 100, which is as deep as OMDb serves.
- `page` (number): Which page this is
- `result_count` (number): How many rows are on this page (at most 10)
- `results` (list): The matching episodes, ten to a page, as OMDb ranks them
- `total_pages` (number): How many pages the matches fill, at ten per page
- `total_results` (number): How many titles matched in total

**Example output**

```json
{
  "has_more": false,
  "page": 1,
  "result_count": 1,
  "results": [
    {
      "imdb_id": "tt1480055",
      "imdb_url": "https://www.imdb.com/title/tt1480055/",
      "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
      "still_running": false,
      "title": "Winter Is Coming",
      "type": "episode",
      "year": "2011",
      "year_end": 2011,
      "year_start": 2011
    }
  ],
  "total_pages": 1,
  "total_results": 3
}
```

### Search films

Search OMDb for films by title and return a page of matches. Series and episodes are left out. A search that matches nothing returns no rows rather than failing.

**Inputs**

- Search for (`query`, text, required): The title to search for. OMDb refuses a term that matches too many titles, so prefer a distinctive one over a single common word.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.
- Page (`page`, number): Which page of results to return. OMDb serves ten per page and accepts pages 1-100, so the deepest result it will reach is the 1,000th. From 1 to 100. Default: `1`.

**Outputs**

- `has_more` (true/false): Whether another page can be fetched. False on the last page and on page 100, which is as deep as OMDb serves.
- `page` (number): Which page this is
- `result_count` (number): How many rows are on this page (at most 10)
- `results` (list): The matching films, ten to a page, as OMDb ranks them
- `total_pages` (number): How many pages the matches fill, at ten per page
- `total_results` (number): How many titles matched in total

**Example output**

```json
{
  "has_more": true,
  "page": 1,
  "result_count": 1,
  "results": [
    {
      "imdb_id": "tt1375666",
      "imdb_url": "https://www.imdb.com/title/tt1375666/",
      "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
      "still_running": false,
      "title": "Inception",
      "type": "movie",
      "year": "2010",
      "year_end": 2010,
      "year_start": 2010
    }
  ],
  "total_pages": 2,
  "total_results": 14
}
```

### Search series

Search OMDb for TV series by title and return a page of matches. Films and episodes are left out. A search that matches nothing returns no rows rather than failing.

**Inputs**

- Search for (`query`, text, required): The title to search for. OMDb refuses a term that matches too many titles, so prefer a distinctive one over a single common word.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.
- Page (`page`, number): Which page of results to return. OMDb serves ten per page and accepts pages 1-100, so the deepest result it will reach is the 1,000th. From 1 to 100. Default: `1`.

**Outputs**

- `has_more` (true/false): Whether another page can be fetched. False on the last page and on page 100, which is as deep as OMDb serves.
- `page` (number): Which page this is
- `result_count` (number): How many rows are on this page (at most 10)
- `results` (list): The matching series, ten to a page, as OMDb ranks them
- `total_pages` (number): How many pages the matches fill, at ten per page
- `total_results` (number): How many titles matched in total

**Example output**

```json
{
  "has_more": false,
  "page": 1,
  "result_count": 1,
  "results": [
    {
      "imdb_id": "tt0944947",
      "imdb_url": "https://www.imdb.com/title/tt0944947/",
      "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
      "still_running": false,
      "title": "Game of Thrones",
      "type": "series",
      "year": "2011-2019",
      "year_end": 2019,
      "year_start": 2011
    }
  ],
  "total_pages": 1,
  "total_results": 6
}
```

### Search titles

Search OMDb for films, series and episodes by name and return a page of matches. Each row carries an IMDb ID a later step can look up for the full record. A search that matches nothing returns no rows rather than failing.

**Inputs**

- Search for (`query`, text, required): The title to search for. OMDb refuses a term that matches too many titles, so prefer a distinctive one over a single common word.
- Year of release (`year`, number): Optional. Only match a title released in this year - useful to tell remakes apart, for example 'Dune' in 1984 from 'Dune' in 2021. From 1850 to 2200.
- Page (`page`, number): Which page of results to return. OMDb serves ten per page and accepts pages 1-100, so the deepest result it will reach is the 1,000th. From 1 to 100. Default: `1`.

**Outputs**

- `has_more` (true/false): Whether another page can be fetched. False on the last page and on page 100, which is as deep as OMDb serves.
- `page` (number): Which page this is
- `result_count` (number): How many rows are on this page (at most 10)
- `results` (list): The matching titles, ten to a page, as OMDb ranks them
- `total_pages` (number): How many pages the matches fill, at ten per page
- `total_results` (number): How many titles matched in total

**Example output**

```json
{
  "has_more": true,
  "page": 1,
  "result_count": 1,
  "results": [
    {
      "imdb_id": "tt1375666",
      "imdb_url": "https://www.imdb.com/title/tt1375666/",
      "poster_url": "https://m.media-amazon.com/images/M/MV5BMjAxMzY3NjcxNF5BMl5BanBnXkFtZTcwNTI5OTM0Mw@@._V1_SX300.jpg",
      "still_running": false,
      "title": "Inception",
      "type": "movie",
      "year": "2010",
      "year_end": 2010,
      "year_start": 2010
    }
  ],
  "total_pages": 4,
  "total_results": 38
}
```