Skip to content

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.

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_year1 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.

imdbfilter.png

  1. 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

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