From 3a5200312208bc17e8bc205481fb42932ba57016 Mon Sep 17 00:00:00 2001 From: Yozora XCII Date: Mon, 18 Mar 2024 13:23:20 +0000 Subject: [PATCH] Clarify `AND` and `OR` lists for TMDB Discover builder --- docs/files/builders/tmdb.md | 131 ++++++++++++++++++------------------ 1 file changed, 67 insertions(+), 64 deletions(-) diff --git a/docs/files/builders/tmdb.md b/docs/files/builders/tmdb.md index 5166e60a..a2c29da1 100644 --- a/docs/files/builders/tmdb.md +++ b/docs/files/builders/tmdb.md @@ -420,8 +420,6 @@ collections: Uses [TMDb's Discover Search](https://developer.themoviedb.org/docs/search-and-query-for-details) to find every movie/show based on the [movie search parameters](https://developers.themoviedb.org/3/discover/movie-discover) or [show search parameters](https://developers.themoviedb.org/3/discover/tv-discover) provided. -I've observed many attributes that begin with `with_` or `without_` being able to use `|` as an `OR` and `&` as an `AND` when specifying multiple items even though it's not listed as possible. - The `sync_mode: sync` and `collection_order: custom` Setting are recommended since the lists are continuously updated and in a specific order. | Type | Description | @@ -435,50 +433,55 @@ The `sync_mode: sync` and `collection_order: custom` Setting are recommended sin ### Discover Movies Parameters -| Movie Parameters | Description | -|:--------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `limit` | Specify how many movies you want returned by the query.
**Type:** Integer
**Default:** 100 | -| `region` | Specify a [ISO 3166-1 code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) to filter release dates. Must be uppercase. Will use the `region` specified in the [TMDb Config](../../config/tmdb.md) by default.
**Type:** `^[A-Z]{2}$` | -| `sort_by` | Choose from one of the many available sort options.
**Type:** Any [sort options](#sort-options) 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.
**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.
**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.
**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.
**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.
**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.
**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_original_language` | Specify an ISO 639-1 string to filter results by their original language value.
**Type:** String | -| `with_title_translation` | Specify a language/country string to filter the results by if the item has a type of title 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` | -| `with_overview_translation` | Specify a language/country string to filter the results by if the item has a type of overview 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` | -| `with_watch_providers` | A comma or pipe separated list of watch provider ID's. Combine this filter with `watch_region` in order to filter your results by a specific watch provider in a specific region.
**Type:** String | -| `watch_region` | An [ISO 3166-1 code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). 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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) | -| `with_watch_monetization_types` | In combination with `watch_region`, you can filter by monetization type.
**Type:** 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. + +| Movie Parameters | Description | +|:--------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `limit` | Specify how many movies you want returned by the query.
**Type:** Integer
**Default:** 100 | +| `region` | Specify a [ISO 3166-1 code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) to filter release dates. Must be uppercase. Will use the `region` specified in the [TMDb Config](../../config/tmdb.md) by default.
**Type:** `^[A-Z]{2}$` | +| `sort_by` | Choose from one of the many available sort options.
**Type:** Any [sort options](#sort-options) 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_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 | +| `watch_region` | An [ISO 3166-1 code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). 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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) | +| `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` | ### Discover Shows Parameters +!!!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. + | Show Parameters | Description | |:--------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `limit` | Specify how many movies you want to be returned by the query.
**Type:** Integer
**Default:** 100 | @@ -495,43 +498,43 @@ The `sync_mode: sync` and `collection_order: custom` Setting are recommended sin | `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.
**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.
**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 TV shows that have one of the ID's added as a keyword.
**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 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 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. Combine this filter with `watch_region` in order to filter your results by a specific watch provider in a specific region.
**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 | | `watch_region` | An [ISO 3166-1 code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). 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.
**Type:** String
**Values:** `flatrate`, `free`, `ads`, `rent`, `buy` | -| `with_status` | Filter TV shows by their status.
**Type:** String
**Values:** `0`: Returning Series, `1`: Planned, `2`: In Production, `3`: Ended, `4`: Cancelled, `5`: Pilot | -| `with_type` | Filter TV shows by their type.
**Type:** String
**Values:** `0`: Documentary, `1`: News, `2`: Miniseries, `3`: Reality, `4`: Scripted, `5`: Show, `6`: Video | +| `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` | +| `with_status` | Filter TV shows by their status.
**Type:** String
Can be a comma (`,`) for an AND, or a pipe (`|`) for an OR separated query
**Values:** `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 query
**Type:** String
**Values:** `0`: Documentary, `1`: News, `2`: Miniseries, `3`: Reality, `4`: Scripted, `5`: Show, `6`: Video | ### Sort Options -| Sort Option | Movie Sort | Show Sort | -|:----------------------------|:----------:|:---------:| -| `popularity.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | +| Sort Option | Movie Sort | Show Sort | +|:----------------------------|:---------------------------------------------:|:--------------------------------------------:| +| `popularity.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | | `popularity.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | -| `original_title.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | -| `original_title.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | -| `revenue.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | -| `revenue.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | -| `release_date.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | -| `release_date.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | -| `primary_release_date.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | -| `primary_release_date.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | -| `first_air_date.asc` | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } | -| `first_air_date.desc` | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } | +| `original_title.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `original_title.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `revenue.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `revenue.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `release_date.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `release_date.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `primary_release_date.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `primary_release_date.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `first_air_date.asc` | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } | +| `first_air_date.desc` | :fontawesome-solid-circle-xmark:{ .red } | :fontawesome-solid-circle-check:{ .green } | | `vote_average.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | | `vote_average.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-check:{ .green } | -| `vote_count.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | -| `vote_count.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `vote_count.asc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | +| `vote_count.desc` | :fontawesome-solid-circle-check:{ .green } | :fontawesome-solid-circle-xmark:{ .red } | ```yaml collections: