TMDb Builders¶
You can find items using the features of TheMovieDb.org (TMDb).
TMDb Standard Builders¶
| Attribute | Description | Works with Movies | Works with Shows | Works with Playlists and Custom Sort |
|---|---|---|---|---|
tmdb_discover |
Uses TMDb's Discover Search to find every movie/show based on the movie search parameters or show search parameters provided | |||
tmdb_collection |
Finds every item in the TMDb collection | |||
tmdb_list |
Finds every item in the TMDb List | |||
tmdb_movie |
Finds the movie specified | |||
tmdb_show |
Finds the show specified | |||
tmdb_company |
Finds every item from the TMDb company's movie/show list | |||
tmdb_network |
Finds every item from the TMDb network's show list | |||
tmdb_keyword |
Finds every item from the TMDb keyword's movie/show list |
TMDb Chart Builders¶
| Attribute | Description | Works with Movies | Works with Shows | Works with Playlists and Custom Sort |
|---|---|---|---|---|
tmdb_popular |
Finds the movies/shows in TMDb's Popular Movies/Popular Shows list | |||
tmdb_now_playing |
Finds the movies in TMDb's Now Playing list | |||
tmdb_top_rated |
Finds the movies/shows in TMDb's Top Rated Movies/Top Rated Shows list | |||
tmdb_upcoming |
Finds the movies in TMDb's Upcoming Movies list | |||
tmdb_airing_today |
Finds the shows in TMDb's Airing Today Shows list | |||
tmdb_on_the_air |
Finds the shows in TMDb's On TV Shows list | |||
tmdb_trending_daily |
Finds the movies/shows in TMDb's Trending Daily list | |||
tmdb_trending_weekly |
Finds the movies/shows in TMDb's Trending Weekly list |
TMDb People Builders¶
| Attribute | Description | Works with Movies | Works with Shows | Works with Playlists and Custom Sort |
|---|---|---|---|---|
tmdb_actor |
Finds every item in the TMDb Person's Actor Credits | |||
tmdb_crew |
Finds every item in the TMDb Person's Crew Credits | |||
tmdb_director |
Finds every item in the TMDb Person's Director Credits | |||
tmdb_producer |
Finds every item in the TMDb Person's Producer Credits | |||
tmdb_writer |
Finds every item in the TMDb Person's Writer Credits |
These are the most commonly used TMDb Builders.
Uses TMDb's Discover Search to find every movie/show based on the movie search attributes or show search attributes provided.
The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated
and in a specific order.
| Type | Description |
|---|---|
| String | Any number of alphanumeric characters |
| Integer | Any whole number greater than zero i.e. 2, 10, 50 |
| Number | Any number greater than zero i.e. 2.5, 7.4, 9 |
| Boolean | Must be true or false |
Date: MM/DD/YYYY |
Date that fits the specified format |
Year: YYYY |
Year must be a 4 digit integer i.e. 1990 |
Important
Note that a number of filters support being comma (,) or pipe (|) separated. Comma's are treated like an AND query while pipe's are treated like an OR. This allows for quite complex filtering depending on your desired results.
Bug
We have noticed inconsistent responses from TMDb when using popularity.asc and popularity.desc as the sort order. This can result in movies/shows disappearing from and reapparing in collections/overlays sporadically. We suggest users do not use the popularity sort options with tmdb_discover.
This bug is on TMDb's side and we are awaiting a fix from them.
| Attribute | Description |
|---|---|
limit |
Specify how many movies you want returned by the query. Type: Integer Default: 100 |
region |
Specify a ISO 3166-1 code to filter release dates. Must be uppercase. Will use the region specified in the TMDb Config by default.Type: ^[A-Z]{2}$ |
sort_by |
Choose from one of the many available sort options. Type: Any sort option below Default: popularity.desc |
certification_country |
Used in conjunction with the certification parameter, use this to specify a country with a valid certification. Type: String |
certification |
Filter results with a valid certification from the certification_country parameter.Type: String |
certification.lte |
Filter and only include movies that have a certification that is less than or equal to the specified value. Type: String |
certification.gte |
Filter and only include movies that have a certification that is greater than or equal to the specified value. Type: String |
include_adult |
A filter and include or exclude adult movies. Type: Boolean |
include_video |
A filter and include or exclude videos. Type: Boolean |
primary_release_year |
A filter to limit the results to a specific primary release year. Type: Year: YYYY |
primary_release_date.gte |
Filter and only include movies that have a primary release date that is greater or equal to the specified value. Type: Date: MM/DD/YYYY |
primary_release_date.lte |
Filter and only include movies that have a primary release date that is less than or equal to the specified value. Type: Date: MM/DD/YYYY |
release_date.gte |
Filter and only include movies that have a release date (looking at all release dates) that is greater or equal to the specified value. Type: Date: MM/DD/YYYY |
release_date.lte |
Filter and only include movies that have a release date (looking at all release dates) that is less than or equal to the specified value. Type: Date: MM/DD/YYYY |
with_release_type |
Specify a comma (AND) or pipe (OR) separated value to filter release types by. Type: String Values: 1: Premiere, 2: Theatrical (limited), 3: Theatrical, 4: Digital, 5: Physical, 6: TV |
year |
A filter to limit the results to a specific year (looking at all release dates). Type: Year: YYYY |
vote_count.gte |
Filter and only include movies that have a vote count that is greater or equal to the specified value. Type: Integer |
vote_count.lte |
Filter and only include movies that have a vote count that is less than or equal to the specified value. Type: Integer |
vote_average.gte |
Filter and only include movies that have a rating that is greater or equal to the specified value. Type: Number |
vote_average.lte |
Filter and only include movies that have a rating that is less than or equal to the specified value. Type: Number |
with_cast |
A comma-separated list of person ID's. Only include movies that have one of the ID's added as an actor. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
with_crew |
A comma-separated list of person ID's. Only include movies that have one of the ID's added as a crew member. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
with_people |
A comma-separated list of person ID's. Only include movies that have one of the ID's added as either an actor or a crew member. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
with_companies |
A comma-separated list of production company ID's. Only include movies that have one of the ID's added as a production company. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
without_companies |
Filter the results to exclude the specific production companies you specify here. AND / OR filters are supported. Type: String |
with_genres |
Comma-separated value of genre ids that you want to include in the results. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
without_genres |
Comma-separated value of genre ids that you want to exclude from the results. Type: String |
with_keywords |
A comma-separated list of keyword ID's. Only includes movies that have one of the ID's added as a keyword. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
without_keywords |
Exclude items with certain keywords. You can comma and pipe separate these values to create an 'AND' or 'OR' logic. Type: String |
with_runtime.gte |
Filter and only include movies that have a runtime that is greater or equal to a value. Type: Integer |
with_runtime.lte |
Filter and only include movies that have a runtime that is less than or equal to a value. Type: Integer |
with_origin_country |
Specify an origin country string to filter results by their original country value. Type: String |
with_original_language |
Specify an ISO 639-1 string to filter results by their original language value. Type: String |
with_watch_providers |
A comma or pipe separated list of watch provider ID's. use in conjunction with watch_region, can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
without_watch_providers |
Filter the results to exclude certain watch providers. Type: String |
watch_region |
An ISO 3166-1 code. Combine this filter with with_watch_providers in order to filter your results by a specific watch provider in a specific region.Type: String Values: ISO 3166-1 code |
with_watch_monetization_types |
In combination with watch_region, you can filter by monetization type.Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String Values: flatrate, free, ads, rent, buy |
Important
Note that a number of filters support being comma (,) or pipe (|) separated. Comma's are treated like an AND query while pipe's are treated like an OR. This allows for quite complex filtering depending on your desired results.
| Attributes | Description |
|---|---|
limit |
Specify how many movies you want to be returned by the query. Type: Integer Default: 100 |
sort_by |
Choose from one of the many available sort options. Type: Any sort option below Default: popularity.desc |
air_date.gte |
Filter and only include TV shows that have an air date (by looking at all episodes) that is greater or equal to the specified value. Type: Date: MM/DD/YYYY |
air_date.lte |
Filter and only include TV shows that have an air date (by looking at all episodes) that is less than or equal to the specified value. Type: Date: MM/DD/YYYY |
first_air_date.gte |
Filter and only include TV shows that have a original air date that is greater or equal to the specified value. Can be used in conjunction with the include_null_first_air_dates filter if you want to include items with no air date.Type: Date: MM/DD/YYYY |
first_air_date.lte |
Filter and only include TV shows that have a original air date that is less than or equal to the specified value. Can be used in conjunction with the include_null_first_air_dates filter if you want to include items with no air date.Type: Date: MM/DD/YYYY |
first_air_date_year |
Filter and only include TV shows that have an original air date year that equal to the specified value. Can be used in conjunction with the include_null_first_air_dates filter if you want to include items with no air date.Type: Year: YYYY |
include_adult |
A filter and include or exclude adult movies. Type: Boolean |
include_null_first_air_dates |
Use this filter to include TV shows that don't have an air date while using any of the first_air_date filters.Type: Boolean |
timezone |
Used in conjunction with the air_date.gte/lte filter to calculate the proper UTC offset.Type: String Default: America/New_York |
vote_count.gte |
Filter and only include TV that have a vote count that is greater or equal to the specified value. Type: Integer |
vote_count.lte |
Filter and only include TV that have a vote count that is less than or equal to the specified value. Type: Integer |
vote_average.gte |
Filter and only include TV that have a rating that is greater or equal to the specified value. Type: Number |
vote_average.lte |
Filter and only include TV that have a rating that is less than or equal to the specified value. Type: Number |
with_networks |
Comma-separated value of network ids that you want to include in the results. Type: String |
with_companies |
A comma-separated list of production company ID's. Only include movies that have one of the ID's added as a production company. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
without_companies |
Filter the results to exclude the specific production companies you specify here. AND / OR filters are supported. Type: String |
with_genres |
Comma-separated value of genre ids that you want to include in the results. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
without_genres |
Comma-separated value of genre ids that you want to exclude from the results. Type: String |
with_keywords |
A comma-separated list of keyword ID's. Only includes TV shows that have one of the ID's added as a keyword. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
without_keywords |
Exclude items with certain keywords. You can comma and pipe separate these values to create an 'AND' or 'OR' logic. Type: String |
with_runtime.gte |
Filter and only include TV shows with an episode runtime that is greater than or equal to a value. Type: Integer |
with_runtime.lte |
Filter and only include TV shows with an episode runtime that is less than or equal to a value. Type: Integer |
with_original_language |
Specify an ISO 639-1 string to filter results by their original language value. Type: String |
with_name_translation |
Specify a language/country string to filter the results by if the item has a type of name translation. Type: String Values: ar-AE, ar-SA, bg-BG, bn-BD, ca-ES, ch-GU, cs-CZ, da-DK, de-DE, el-GR, en-US, eo-EO, es-ES, es-MX, eu-ES, fa-IR, fi-FI, fr-CA, fr-FR, he-IL, hi-IN, hu-HU, id-ID, it-IT, ja-JP, ka-GE, kn-IN, ko-KR, lt-LT, ml-IN, nb-NO, nl-NL, no-NO, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sl-SI, sr-RS, sv-SE, ta-IN, te-IN, th-TH, tr-TR, uk-UA, vi-VN, zh-CN, zh-TW |
screened_theatrically |
Filter results to include items that have been screened theatrically. Type: Boolean |
with_watch_providers |
A comma or pipe separated list of watch provider ID's. use in conjunction with watch_region, can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String |
without_watch_providers |
Filter the results to exclude certain watch providers. Type: String |
watch_region |
An ISO 3166-1 code. Combine this filter with with_watch_providers in order to filter your results by a specific watch provider in a specific region.Type: String |
with_watch_monetization_types |
In combination with watch_region, you can filter by monetization type.Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String Values: flatrate, free, ads, rent, buy |
with_status |
Filter TV shows by their status. Type: String Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryValues: 0: Returning Series, 1: Planned, 2: In Production, 3: Ended, 4: Cancelled, 5: Pilot |
with_type |
Filter TV shows by their type. Can be a comma ( ,) for an AND, or a pipe (|) for an OR separated queryType: String Values: 0: Documentary, 1: News, 2: Miniseries, 3: Reality, 4: Scripted, 5: Show, 6: Video |
| Sort Option | Movie Sort | Show Sort |
|---|---|---|
popularity.asc |
||
popularity.desc |
||
title.asc |
||
title.desc |
||
original_title.asc |
||
original_title.desc |
||
name.asc |
||
name.desc |
||
original_name.asc |
||
original_name.desc |
||
revenue.asc |
||
revenue.desc |
||
release_date.asc |
||
release_date.desc |
||
primary_release_date.asc |
||
primary_release_date.desc |
||
first_air_date.asc |
||
first_air_date.desc |
||
vote_average.asc |
||
vote_average.desc |
||
vote_count.asc |
||
vote_count.desc |
collections:
Movies Released in October 2020:
tmdb_discover:
primary_release_date.gte: 10/01/2020
primary_release_date.lte: 10/31/2020
collections:
Popular Movies:
collection_order: custom
sync_mode: sync
tmdb_discover:
sort_by: popularity.desc
collections:
Highest Rated R Movies:
collection_order: custom
sync_mode: sync
tmdb_discover:
certification_country: US
certification: R
sort_by: vote_average.desc
collections:
Most Popular Kids Movies:
collection_order: custom
sync_mode: sync
tmdb_discover:
certification_country: US
certification.lte: G
sort_by: popularity.desc
collections:
Highest Rated Movies From 2010:
collection_order: custom
sync_mode: sync
tmdb_discover:
primary_release_year: 2010
sort_by: vote_average.desc
collections:
Best Dramas From 2014:
collection_order: custom
sync_mode: sync
tmdb_discover:
with_genres: 18
primary_release_year: 2014
sort_by: vote_average.desc
collections:
Highest Rated Science Fiction Movies with Tom Cruise:
collection_order: custom
sync_mode: sync
tmdb_discover:
with_genres: 878
with_cast: 500
sort_by: vote_average.desc
collections:
Highest Grossing Comedy Movies with Will Ferrell:
collection_order: custom
sync_mode: sync
tmdb_discover:
with_genres: 35
with_cast: 23659
sort_by: revenue.desc
collections:
Top Rated Movies with Brad Pitt and Edward Norton:
collection_order: custom
sync_mode: sync
tmdb_discover:
with_people: 287,819
sort_by: vote_average.desc
collections:
Popular Movies with David Fincher and Rooney Mara:
collection_order: custom
sync_mode: sync
tmdb_discover:
with_people: 108916,7467
sort_by: popularity.desc
Finds every item in the TMDb collection.
This Builder is expected to have the full URL to the item or the TMDb ID of the item. Multiple values are supported as either a list or a comma-separated string.
collections:
The Lord of the Rings:
tmdb_collection:
- 121938 #(3)!
The Hobbit:
tmdb_collection: https://www.themoviedb.org/collection/119
Middle Earth:
tmdb_collection_details: #(1)!
- 119 #(2)!
- https://www.themoviedb.org/collection/121938
- You can replace
tmdb_collectionwithtmdb_collection_detailsif you would like to fetch and use the TMDb collection's summary, poster, and background from the list. - You can specify multiple collections in
tmdb_collection_detailsbut it will only use the first one to update the collection details. -
https://www.themoviedb.org/collection/121938-the-hobbit-collection also accepted
-
Posters and background in the library's asset directory will be used over the collection details unless
tmdb_poster/tmdb_backgroundis also specified.
Finds every item in the TMDb List.
This Builder is expected to have the full URL to the item or the TMDb ID of the item. 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.
collections:
Top 50 Grossing Films of All Time (Worldwide):
tmdb_list: 10 #(1)!
collection_order: custom
sync_mode: sync
Marvel & DC Universes:
tmdb_list_details: #(2)!
- 1 #(3)!
- 3
collection_order: custom
sync_mode: sync
- https://www.themoviedb.org/list/10 also accepted
- You can replace
tmdb_listwithtmdb_list_detailsif you would like to fetch and use the TMDb collection's summary, poster, and background from the list - You can specify multiple lists in
tmdb_list_detailsbut it will only use the first one to update the collection details
Finds the movie specified.
This Builder is expected to have the full URL to the item or the TMDb ID of the item. Multiple values are supported as either a list or a comma-separated string.
collections:
Anaconda:
tmdb_movie: #(1)!
- 336560
Wizard of Oz & Wicked:
tmdb_movie_details: #(2)!
- 630 #(3)!
- 402431
- You can replace
tmdb_moviewithtmdb_movie_detailsif you would like to fetch and use the TMDb show's summary, poster, and background from the list - You can specify multiple shows in
tmdb_movie_detailsbut it will only use the first one to update the collection details -
https://www.themoviedb.org/movie/630-the-wizard-of-oz also accepted
-
Posters and background in the library's asset directory will be used over the collection details unless
tmdb_poster/tmdb_backgroundis also specified.
Finds the show specified.
This Builder is expected to have the full URL to the item or the TMDb ID of the item. Multiple values are supported as either a list or a comma-separated string.
collections:
Star Wars (Animated Shows):
tmdb_show:
- 4194 #(1)!
- 60554
Pokémon Evolutions & Chronicles:
tmdb_show_details: #(2)!
- 132636 #(3)!
- 13230
- https://www.themoviedb.org/tv/4194-star-wars-the-clone-wars also accepted
- You can replace
tmdb_showwithtmdb_show_detailsif you would like to fetch and use the TMDb show's summary, poster, and background from the list -
You can specify multiple shows in
tmdb_show_detailsbut it will only use the first one to update the collection details -
Posters and background in the library's asset directory will be used over the collection details unless
tmdb_poster/tmdb_backgroundis also specified.
Finds every movie from the TMDb company's movie list.
This Builder is expected to have the full URL to the item or the TMDb ID of the item. Multiple values are supported as either a list or a comma-separated string.
- https://www.themoviedb.org/company/10342 also accepted
Finds every item from the TMDb network's movie/show list.
This Builder is expected to have the full URL to the item or the TMDb ID of the item. Multiple values are supported as either a list or a comma-separated string.
- https://www.themoviedb.org/network/16 also accepted
These Builders use TMDb's Chart data
Finds the movies/shows in TMDb's Popular Movies/Popular Shows list.
Use tmdb_region with this Builder to set the region.
This Builder is expected to have an integer (number) value of how many items to query
The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated
and in a specific order.
Finds the movies in TMDb's Now Playing list.
Use tmdb_region with this Builder to set the region.
This Builder is expected to have an integer (number) value of how many items to query
The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated
and in a specific order.
Finds the movies/shows in TMDb's Top Rated Movies/Top Rated Shows list.
Use tmdb_region with this Builder to set the region.
This Builder is expected to have an integer (number) value of how many items to query
The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated
and in a specific order.
Finds the movies in TMDb's Upcoming Movies list.
Use tmdb_region with this Builder to set the region.
This Builder is expected to have an integer (number) value of how many items to query
The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated
and in a specific order.
Finds the shows in TMDb's Airing Today Shows list.
This Builder is expected to have an integer (number) value of how many items to query
The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated
and in a specific order.
Finds the shows in TMDb's On TV Shows list.
This Builder is expected to have an integer (number) value of how many items to query
The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated
and in a specific order.
Finds the movies/shows in TMDb's Trending Daily list.
This Builder is expected to have an integer (number) value of how many items to query
The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated
and in a specific order.
Finds the movies/shows in TMDb's Trending Weekly list.
This Builder is expected to have an integer (number) value of how many items to query
The sync_mode: sync and collection_order: custom Setting are recommended since the lists are continuously updated
and in a specific order.
These Builders use data on people's credited work.
People Collections
As Plex does not allow People to be part of Collections, Kometa will instead add any media that the person is associated with based om the Builder criteria.
You can not have a Collection of "Top 10 Actors" for example, as Plex does not allow this.
Finds every item in the TMDb Person's Actor Credits.
collections:
Robin Williams:
tmdb_actor: 2157 #(1)!
Hemsworth Brothers:
tmdb_actor_details: #(2)!
- 74568 #(3)!
- 96066
- 216986
- https://www.themoviedb.org/person/2157-robin-williams also accepted
- You can replace
tmdb_actorwithtmdb_actor_detailsif you would like to fetch and use the TMDb Person's biography and profile from the list - You can specify multiple people in
tmdb_actor_detailsbut it will only use the first one to update the collection details
Finds every item in the TMDb Person's Crew Credits.
collections:
Quentin Tarantino:
tmdb_crew: 138 #(1)!
The Skarsgards Family
tmdb_crew_details: #(2)!
- 28846 #(3)!
- 137905
- 63764
- 1640
- 1281937
- 2367741
- https://www.themoviedb.org/person/138-quentin-tarantino also accepted
- You can replace
tmdb_crewwithtmdb_crew_detailsif you would like to fetch and use the TMDb Person's biography and profile from the list - You can specify multiple people in
tmdb_crew_detailsbut it will only use the first one to update the collection details
Finds every item in the TMDb Person's Director Credits.
collections:
Steven Spielberg:
tmdb_director: 488 #(1)!
The Russo Brothers:
tmdb_director_details: #(2)!
- 19271 #(3)!
- 19272
-
https://www.themoviedb.org/person/488-steven-spielberg also accepted¶
- You can replace
tmdb_directorwithtmdb_director_detailsif you would like to fetch and use the TMDb Person's biography and profile from the list - You can specify multiple people in
tmdb_director_detailsbut it will only use the first one to update the collection details
Finds every item in the TMDb Person's Producer Credits.
collections:
Adam Sandler:
tmdb_producer: 19292 #(3)!
The Wachowskis:
tmdb_producer_details: #(1)!
- 9339 #(2)!
- 9340
- You can replace
tmdb_producerwithtmdb_producer_detailsif you would like to fetch and use the TMDb collection's summary, poster, and background from the list - You can specify multiple producers in
tmdb_producer_detailsbut it will only use the first one to update the collection details - https://www.themoviedb.org/person/19292-adam-sandler also accepted
Finds every item in the TMDb Person's Writer Credits.
collections:
Woody Allen:
tmdb_writer:
- 1243 #(3)!
The Daniels::
tmdb_writer_details: #(1)!
- 1383612 #(2)!
- https://www.themoviedb.org/person/1317730
- You can replace
tmdb_writerwithtmdb_writer_detailsif you would like to fetch and use the TMDb collection's summary, poster, and background from the list - You can specify multiple people in
tmdb_writer_detailsbut it will only use the first one to update the collection details - https://www.themoviedb.org/person/1243-woody-allen also accepted