IMDb Builders¶

You can find items using the features of IMDb.com (IMDb).

Attribute	Description	Works with Movies	Works with Shows	Works with Playlists and Custom Sort
`imdb_id`	Gets the movie/show specified.
`imdb_chart`	Gets every movie/show in an IMDb Chart like IMDb Top 250 Movies.
`imdb_list`	Gets every movie/show in an IMDb List
`imdb_watchlist`	Gets every movie/show in an IMDb User's Watchlist.
`imdb_award`	Gets every movie/show in an IMDb Event.
`imdb_search`	Gets every movie/show in an IMDb Search. Can also be used for Keyword searches.

IMDb ID¶

Gets the movie/show specified.

The expected input is an IMDb ID. Multiple values are supported as either a list or a comma-separated string.

collections:
  Star Wars (Animated Shows):
    imdb_id: tt0458290, tt2930604

IMDb Chart¶

Finds every item in an IMDb Chart.

The expected input are the options below. Multiple values are supported as either a list or a comma-separated string.

The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated and in a specific order.

Name	Attribute	Works with Movies	Works with Shows
Box Office	`box_office`
Most Popular Movies	`popular_movies`
Top 250 Movies	`top_movies`
Top Rated English Movies	`top_english`
Most Popular TV Shows	`popular_shows`
Top 250 TV Shows	`top_shows`
Top Rated Indian Movies	`top_indian`
Lowest Rated Movies	`lowest_rated`

collections:
  IMDb Top 250:
    imdb_chart: top_movies
    collection_order: custom
    sync_mode: sync

IMDb List¶

Important Notice

Due to recent changes in IMDb's code, imdb_list can no longer be used for any url which starts with https://www.imdb.com/search/ or https://www.imdb.com/filmosearch/.

These must instead use the IMDb Search Builder

Finds every item in an IMDb List.

The expected input is an IMDb List URL. Multiple values are supported as a list only a comma-separated string will not work.

The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated and in a specific order.

collections:
  James Bonds:
    imdb_list: https://www.imdb.com/list/ls006405458
    collection_order: custom
    sync_mode: sync

You can also limit the number of items to search for by using the limit and url parameters under imdb_list.

collections:
  Christmas:
    imdb_list:
      - url: https://www.imdb.com/list/ls025976544/
        limit: 10
      - url: https://www.imdb.com/list/ls003863000/
        limit: 10
      - url: https://www.imdb.com/list/ls027454200/
        limit: 10
      - url: https://www.imdb.com/list/ls027886673/
        limit: 10
      - url: https://www.imdb.com/list/ls097998599/
        limit: 10
    sync_mode: sync
    collection_order: alpha

IMDb Watchlist¶

Finds every item in an IMDb User's Watchlist.

The expected input is an IMDb User ID (example: ur12345678). Multiple values are supported as a list or as a comma-separated string.

The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated and in a specific order.

collections:
  My Watch Watchlist:
    imdb_watchlist: ur64054558
    collection_order: custom
    sync_mode: sync

collections:
  My Friends Watchlists:
    imdb_watchlist: ur64054558, ur12345678
    collection_order: custom
    sync_mode: sync

collections:
  My Friends Watchlists:
    imdb_watchlist: 
      - ur64054558
      - ur12345678
    collection_order: custom
    sync_mode: sync

IMDb Award¶

Finds every item in an IMDb Event.

Award Parameter	Description
`event_id`	Specify the IMDb Event ID to search. This attribute is required. Options: The ID found in the URLs linked on the IMDb Events Page. (ex. `ev0000003`)
`event_year`¹	Specify the year of the Event to look at. This attribute is required. Options: Any year, list of years, or year range (ex. `2000-2009` or `2000-current`) from the years under the Event History Sidebar on an Event page.
`award_filter`	Filter by the Award heading. Can only accept multiple values as a list. Options: Any Black Award heading on an Event Page.
`category_filter`	Filter by the Category heading. Can only accept multiple values as a list. Options: Any Gold/Yellow Category heading on an Event Page.
`winning`	Filter by if the Item Won the award. Options: `true`/`false` Default: `false`

Example Award and Category Filter

In the below example, "Grand Jury Prize" is the award_filter, and "Documentary" is the category_filter. You can use both of these filters together.

When using multiple years the only available Event IDs are:

event_ids:
- ev0000003 # Academy Awards, USA
- ev0000091 # Berlin International Film Festival
- ev0000123 # BAFTA Awards
- ev0000133 # Critics Choice Awards
- ev0000147 # Cannes Film Festival
- ev0000157 # César Awards, France
- ev0000223 # Primetime Emmy Awards
- ev0000292 # Golden Globes, USA
- ev0000349 # Film Independent Spirit Awards
- ev0000468 # National Film Preservation Board, USA
- ev0000530 # People's Choice Awards, USA
- ev0000558 # Razzie Awards
- ev0000598 # Screen Actors Guild Awards
- ev0000631 # Sundance Film Festival
- ev0000659 # Toronto International Film Festival
- ev0000681 # Venice Film Festival

collections:
  Academy Award Winners 2023:
    imdb_award: 
      event_id: ev0000003
      event_year: 2023
      winning: true

collections:
  Academy Award 2023 Best Picture Nominees:
    imdb_award: 
      event_id: ev0000003
      event_year: 2023
      category_filter: Best Motion Picture of the Year

IMDb Search¶

Finds every item using an IMDb Advance Title Search.

The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated and in a specific order.

Tip

We strongly recommend you use the IMDb Search website to manually verify that the options you have selected are valid.

You can also view the available keywords on the IMDb Keyword Search page.

Search Parameter	Description
`limit`	Specify how items you want returned by the query. Options: Any Integer greater than `0` Default: `100`
`sort_by`	Choose from one of the many available sort options. Options: `popularity.asc`, `popularity.desc`, `title.asc`, `title.desc`, `rating.asc`, `rating.desc`, `votes.asc`, `votes.desc`, `box_office.asc`, `box_office.desc`, `runtime.asc`, `runtime.desc`, `year.asc`, `year.desc`, `release.asc`, `release.desc` Default: `popularity.asc`
`title`	Search by title name. Options: Any String
`type`	Item must match at least one given type. Can be a comma-separated list. Options: `movie`, `tv_series`, `short`, `tv_episode`, `tv_mini_series`, `tv_movie`, `tv_special`, `tv_short`, `video_game`, `video`, `music_video`, `podcast_series`, `podcast_episode`
`type.not`	Item must not match any of the given types. Can be a comma-separated list. Options: `movie`, `tv_series`, `short`, `tv_episode`, `tv_mini_series`, `tv_movie`, `tv_special`, `tv_short`, `video_game`, `video`, `music_video`, `podcast_series`, `podcast_episode`
`release.after`	Item must have been released after the given date. Options: `today` or Date in the format `YYYY-MM-DD`
`release.before`	Item must have been released before the given date. Options: `today` or Date in the format `YYYY-MM-DD`
`rating.gte`	Item must have an IMDb Rating greater than or equal to the given number. Options: Any Number `0.1` - `10.0` Example: `7.5`
`rating.lte`	Item must have an IMDb Rating less than or equal to the given number. Options: Any Number `0.1` - `10.0` Example: `7.5`
`votes.gte`	Item must have a Number of Votes greater than or equal to the given number. Options: Any Integer greater than `0` Example: `1000`
`votes.lte`	Item must have a Number of Votes less than or equal to the given number. Options: Any Integer greater than `0` Example: `1000`
`genre`	Item must match all genres given. Can be a comma-separated list. Options: `action`, `adventure`, `animation`, `biography`, `comedy`, `documentary`, `drama`, `crime`, `family`, `history`, `news`, `short`, `western`, `sport`, `reality-tv`, `horror`, `fantasy`, `film-noir`, `music`, `romance`, `talk-show`, `thriller`, `war`, `sci-fi`, `musical`, `mystery`, `game-show`
`genre.any`	Item must match at least one given genre. Can be a comma-separated list. Options: `action`, `adventure`, `animation`, `biography`, `comedy`, `documentary`, `drama`, `crime`, `family`, `history`, `news`, `short`, `western`, `sport`, `reality-tv`, `horror`, `fantasy`, `film-noir`, `music`, `romance`, `talk-show`, `thriller`, `war`, `sci-fi`, `musical`, `mystery`, `game-show`
`genre.not`	Item must not match any og the given genres. Can be a comma-separated list. Options: `action`, `adventure`, `animation`, `biography`, `comedy`, `documentary`, `drama`, `crime`, `family`, `history`, `news`, `short`, `western`, `sport`, `reality-tv`, `horror`, `fantasy`, `film-noir`, `music`, `romance`, `talk-show`, `thriller`, `war`, `sci-fi`, `musical`, `mystery`, `game-show`
`event`	Item must have been nominated for a category at the event given. Can be a comma-separated list. Options: `cannes`, `choice`, `spirit`, `sundance`, `bafta`, `oscar`, `emmy`, `golden`, `oscar_picture`, `oscar_director`, `national_film_board_preserved`, `razzie`, or any IMDb Event ID (ex. `ev0050888`)
`event.winning`	Item must have won a category at the event given. Can be a comma-separated list. Options: `cannes`, `choice`, `spirit`, `sundance`, `bafta`, `oscar`, `emmy`, `golden`, `oscar_picture`, `oscar_director`, `national_film_board_preserved`, `razzie`, or any IMDb Event ID (ex. `ev0050888`)
`imdb_top`	Item must be in the top number of given Movies. Options: Any Integer greater than `0`
`imdb_bottom`	Item must be in the bottom number of given Movies. Options: Any Integer greater than `0`
`topic`	Item must match at least one given topic. Can be a comma-separated list. Options: `alternate_version`, `award`, `business_info`, `crazy_credit`, `goof`, `location`, `plot`, `quote`, `soundtrack`, `technical`, `trivia`
`topic.not`	Item must not match any of the given topic. Can be a comma-separated list. Options: `alternate_version`, `award`, `business_info`, `crazy_credit`, `goof`, `location`, `plot`, `quote`, `soundtrack`, `technical`, `trivia`
`alternate_version`	Item's Alternate Version must contain all the given strings. Can be a comma-separated list. Options: Any String
`alternate_version.any`	Item's Alternate Version must contain at least one of the given strings. Can be a comma-separated list. Options: Any String
`alternate_version.not`	Item's Alternate Version must not contain any of the given strings. Can be a comma-separated list. Options: Any String
`crazy_credit`	Item's Crazy Credits must contain all the given strings. Can be a comma-separated list. Options: Any String
`crazy_credit.any`	Item's Crazy Credits must contain at least one of the given strings. Can be a comma-separated list. Options: Any String
`crazy_credit.not`	Item's Crazy Credits must not contain any of the given strings. Can be a comma-separated list. Options: Any String
`location`	Item's Location must contain all the given strings. Can be a comma-separated list. Options: Any String
`location.any`	Item's Location must contain at least one of the given strings. Can be a comma-separated list. Options: Any String
`location.not`	Item's Location must not contain any of the given strings. Can be a comma-separated list. Options: Any String
`goof`	Item's Goofs must contain all the given strings. Can be a comma-separated list. Options: Any String
`goof.any`	Item's Goofs must contain at least one of the given strings. Can be a comma-separated list. Options: Any String
`goof.not`	Item's Goofs must not contain any of the given strings. Can be a comma-separated list. Options: Any String
`plot`	Item's Plot must contain all the given strings. Can be a comma-separated list. Options: Any String
`plot.any`	Item's Plot must contain at least one of the given strings. Can be a comma-separated list. Options: Any String
`plot.not`	Item's Plot must not contain any of the given strings. Can be a comma-separated list. Options: Any String
`quote`	Item's Quote must contain all the given strings. Can be a comma-separated list. Options: Any String
`quote.any`	Item's Quote must contain at least one of the given strings. Can be a comma-separated list. Options: Any String
`quote.not`	Item's Quote must not contain any of the given strings. Can be a comma-separated list. Options: Any String
`soundtrack`	Item's Soundtrack must contain all the given strings. Can be a comma-separated list. Options: Any String
`soundtrack.any`	Item's Soundtrack must contain at least one of the given strings. Can be a comma-separated list. Options: Any String
`soundtrack.not`	Item's Soundtrack must not contain any of the given strings. Can be a comma-separated list. Options: Any String
`trivia`	Item's Trivia must contain all the given strings. Can be a comma-separated list. Options: Any String
`trivia.any`	Item's Trivia must contain at least one of the given strings. Can be a comma-separated list. Options: Any String
`trivia.not`	Item's Trivia must not contain any of the given strings. Can be a comma-separated list. Options: Any String
`company`	Item must have been released by any company given. Can be a comma-separated list. Options: `fox`, `dreamworks`, `mgm`, `paramount`, `sony`, `universal`, `disney`, `warner`, or any IMDb Company ID (ex. `co0023400`)
`content_rating`	Item must have the given content rating. Can be a list. Options: Dictionary with two attributes `rating` and `region` `rating`: Any String to match the content rating `region`: 2 Digit ISO 3166 Country Code
`country`	Item must match with every given country. Can be a comma-separated list. Options: 2 Digit ISO 3166 Country Code
`country.any`	Item must match at least one given country. Can be a comma-separated list. Options: 2 Digit ISO 3166 Country Code
`country.not`	Item must not match any given country. Can be a comma-separated list. Options: 2 Digit ISO 3166 Country Code
`country.origin`	Item must match any given country as the origin country. Can be a comma-separated list. Options: 2 Digit ISO 3166 Country Code
`keyword`	Item must match with every given keyword. Can be a comma-separated list. Options: Any Valid IMDb Keyword
`keyword.any`	Item must match at least one given keyword. Can be a comma-separated list. Options: Any Valid IMDb Keyword
`keyword.not`	Item must not match any given keyword. Can be a comma-separated list. Options: Any Valid IMDb Keyword
`series`	Item must match at least one given series. Can be a comma-separated list. Options: Any IMDb ID (ex. `tt0096697`)
`series.not`	Item must not match any given series. Can be a comma-separated list. Options: Any IMDb ID (ex. `tt0096697`)
`list`	Item must be on every given list. Can be a comma-separated list. Options: Any IMDb List ID (ex. `ls000024621`)
`list.any`	Item must be on at least one given lists. Can be a comma-separated list. Options: Any IMDb List ID (ex. `ls000024621`)
`list.not`	Item must not be on any given lists. Can be a comma-separated list. Options: Any IMDb List ID (ex. `ls000024621`)
`language`	Item must match any given language. Can be a comma-separated list. Options: ISO 639-2 Language Codes
`language.any`	Item must match at least one given language. Can be a comma-separated list. Options: ISO 639-2 Language Codes
`language.not`	Item must not match any given language. Can be a comma-separated list. Options: ISO 639-2 Language Codes
`language.primary`	Item must match any given language as the primary language. Can be a comma-separated list. Options: ISO 639-2 Language Codes
`popularity.gte`	Item must have a Popularity greater than or equal to the given number. Options: Any Integer greater than `0` Example: `1000`
`popularity.lte`	Item must have a Popularity less than or equal to the given number. Options: Any Integer greater than `0` Example: `1000`
`cast`	Item must have all the given cast members. Can be a comma-separated list. Options: Any IMDb Person ID (ex. `nm0000138`)
`cast.any`	Item must have any of the given cast members. Can be a comma-separated list. Options: Any IMDb Person ID (ex. `nm0000138`)
`cast.not`	Item must not have any of the given cast members. Can be a comma-separated list. Options: Any IMDb Person ID (ex. `nm0000138`)
`runtime.gte`	Item must have a Runtime greater than or equal to the given number. Options: Any Integer greater than `0` Example: `1000`
`runtime.lte`	Item must have a Runtime less than or equal to the given number. Options: Any Integer greater than `0` Example: `1000`
`adult`	Include adult titles in the search results. Options: `true`/`false`

Examples¶

collections:
  IMDb Popular:
    imdb_search:
      type: movie
      sort_by: popularity.asc
      limit: 50
    collection_order: custom
    sync_mode: sync

collections:
  Top Action:
    imdb_search:
      type: movie
      release.after: 1990-01-01
      rating.gte: 5
      votes.gte: 100000
      genre: action
      sort_by: rating.desc
      limit: 100

You can also find episodes using imdb_search like so.

collections:
  The Simpsons Top 100 Episodes:
    collection_order: custom
    builder_level: episode
    sync_mode: sync
    imdb_search:
      type: tv_episode
      series: tt0096697
      sort_by: rating.desc
      limit: 100
    summary: The top 100 Simpsons episodes by IMDb user rating