Skip to content

Kometa Wiki

Movie

TMDb Discover (Movies)¶

Uses TMDb's Discover Search to find every movie based on the movie 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.

Important

Note that a number of filters support being comma (,) or pipe (|) separated. Commas are treated like an AND query while pipes are treated like an OR. This allows for quite complex filtering depending on your desired results.

Value Types¶

These are the types of values you can use in your TMDb Discover queries. The type and formatting of attributes such as date and year is important to know when building your queries.

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

Discover Attributes¶

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 query Type: 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 query Type: 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 query 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 query Type: 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 query Type: 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 query Type: 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 query Type: 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 query Type: String Values: `flatrate`, `free`, `ads`, `rent`, `buy`

Sort Options¶

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`

Example TMDb Discover Builder(s)¶

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

collections:
  Top Rated Dramas:
    collection_order: custom
    sync_mode: sync
    tmdb_discover:
      with_genres: 18
      sort_by: vote_average.desc
      vote_count.gte: 10

collections:
  Highest Grossing R Movies with Liam Neeson:
    collection_order: custom
    sync_mode: sync
    tmdb_discover:
      certification_country: US
      certification: R
      sort_by: revenue.desc
      with_cast: 3896

YAML Lists Explained

YAML supports different ways to define lists. Below are some common methods:

1. List Within a Mapping

fruits:
  - apple
  - banana
  - cherry

2. Inline Style

fruits: [ apple, banana, cherry ]

Each style can be used depending on your needs. The block style is typically more readable for longer lists, while the inline style is compact and useful for short lists.

YAML Dictionaries Explained

Dictionaries are used to associate key/value pairs that are unordered. Dictionaries can be nested by increasing the indentation, or new dictionaries can be created at the same level by resolving the previous one.

cache: true
cache_expiration: 60

The "keys" are cache and cache_expiration and the "values" are true and 60 respectively.

These filters only work if the URL is to the List View of the Letterboxd list (i.e. it should have /detail/ in the URL) or to an account's Reviews (i.e. it should have /USERNAME/films/reviews/ in the URL).

This filter only works if the URL is to the List View of the Letterboxd list (i.e. it should have /detail/ in the URL).

When title is not provided and the mapping name was not specified as an ID, the default behaviour is to use the mapping name as title for matching.

When mapping_id is not provided and the mapping name was specified as an ID, the default behaviour is to use the mapping name as mapping_id for matching.

When the server does not have a Plex Pass then the Edition Field is not accessible. In this scenario, Kometa will check the movie's filepath for {edition-...} to determine what the edition is.

Each default has a key that when calling to effect a specific collection/overlay you must replace <<key>> with when calling.

You can use current_year to have Kometa use the current year's value. This can be combined with a -# at the end to subtract that number of years. i.e. current_year-2

Filters using the special episodes/tracks filter with the default percent.

Also filters out missing movies/shows from being added to Radarr/Sonarr. These values also cannot use the count modifiers.

You can use current_year to have Kometa use the current year's value. This can be combined with a -# at the end to subtract that number of years. i.e. current_year-2

Also filters out missing movies/shows from being added to Radarr/Sonarr. These values also cannot use the count modifiers.

Filters using the special episodes/tracks filter with the default percent.

Also filters out missing movies/shows from being added to Radarr/Sonarr. These values also cannot use the count modifiers.

Filters using the special episodes/tracks filter with the default percent.

You can use current_year to have Kometa use the current year's value. This can be combined with a -# at the end to subtract that number of years. i.e. current_year-2

Filters using the special episodes/tracks filter with the default percent.

Also filters out missing movies/shows from being added to Radarr/Sonarr. These values also cannot use the count modifiers.

Filters using the special episodes/tracks filter with the default percent.

Also filters out missing movies/shows from being added to Radarr/Sonarr. These values also cannot use the count modifiers.

The field will be locked if a previous mass_poster_update or mass_background_update was run, or if an Overlay has been applied.

Kometa checks for the Overlay label on the item in Plex to determine if an Overlay is applied.