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`
Lowest Rated Movies	`lowest_rated`
Top Rated Indian Movies	`top_indian`
Top Rated Tamil Movies	`top_tamil`
Top Rated Telugu Movies	`top_telugu`
Top Rated Malayalam Movies	`top_malayalam`
Trending Indian Movies & Shows	`trending_india`
Trending Tamil Movies	`trending_tamil`
Trending Telugu Movies	`trending_telugu`

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.

List Parameter	Description
`list_id`	Specify the IMDb List ID. This attribute is required. Options: The ID that starts with `ls` found in the URL of the list. (ex. `ls005526372`)
`limit`	Specify how items you want returned by the query. Options: Any Integer `0` or greater where `0` get all items. Default: `0`
`sort_by`	Choose from one of the many available sort options. Options: `custom.asc`, `custom.desc`, `title.asc`, `title.desc`, `rating.asc`, `rating.desc`, `popularity.asc`, `popularity.desc`, `votes.asc`, `votes.desc`, `release.asc`, `release.desc`, `runtime.asc`, `runtime.desc`, `added.asc`, `added.desc` Default: `custom.asc`

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: 
      list_id: ls006405458
      limit: 100
      sort_by: rating.asc
    collection_order: custom
    sync_mode: sync

You can search multiple lists in one collection by using a list.

collections:
  Christmas:
    imdb_list:
      - list_id: ls025976544
        limit: 10
        sort_by: rating.asc
      - list_id: ls003863000
        limit: 10
        sort_by: rating.asc
      - list_id: ls027454200
        limit: 10
        sort_by: rating.asc
      - list_id: ls027886673
        limit: 10
        sort_by: rating.asc
      - list_id: ls097998599
        limit: 10
        sort_by: rating.asc
    sync_mode: sync
    collection_order: alpha

IMDb Watchlist¶

Finds every item in an IMDb User's Watchlist.

List Parameter	Description
`user_id`	Specify the User ID for the IMDb Watchlist. This attribute is required. Options: The ID that starts with `ur` found in the URL of the watchlist. (ex. `ur12345678`)
`limit`	Specify how items you want returned by the query. Options: Any Integer `0` or greater where `0` get all items. Default: `0`
`sort_by`	Choose from one of the many available sort options. Options: `custom.asc`, `custom.desc`, `title.asc`, `title.desc`, `rating.asc`, `rating.desc`, `popularity.asc`, `popularity.desc`, `votes.asc`, `votes.desc`, `release.asc`, `release.desc`, `runtime.asc`, `runtime.desc`, `added.asc`, `added.desc` Default: `custom.asc`

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:
  My Watch Watchlist:
    imdb_watchlist: 
      user_id: ur64054558
      sort_by: rating.asc
    collection_order: custom
    sync_mode: sync

collections:
  My Friends Watchlists:
    imdb_watchlist: 
      - user_id: ur64054558
        sort_by: rating.asc
        limit: 100
      - user_id: ur12345678
        sort_by: rating.asc
        limit: 100
    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
- ev0000245 # Filmfare Awards
- ev0000280 # German Film Awards
- ev0000292 # Golden Globes, USA
- ev0000349 # Film Independent Spirit Awards
- ev0000361 # Awards of the International Indian Film Academy
- ev0000415 # Zee Cine Awards
- ev0000467 # National Film Awards, India
- 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
- ev0001931 # Indian Television Academy Awards, India
- ev0005699 # Zee Rishtey Awards
- ev0005770 # Nickelodeon Kids' Choice Awards, India
- ev0011808 # Indian Film Festival Of Melbourne
- ev0035513 # Filmfare OTT Awards
- ev0036701 # Critics’ Choice Shorts and Series Awards, India
- ev0057191 # Iconic Gold Awards
- ev0060658 # Bollywood Film Journalist Awards
- ev0073358 # International Iconic Awards

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 `0` or greater where `0` get all items. 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 of 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