Parameter Reference

This is a comprehensive list of parameters for the Insights API:

Filters: Specify what kind of results you want. These parameters narrow the results to a specific entity type (like movies, places, or artists), tags, or location.
Signals: Specify what to base the recommendations on. These parameters influence the ranking by providing context, such as audience demographics, user interests, or related entities.
Output: Specify how the results are presented. These parameters control aspects like the number of results displayed (take) and which page of results to show (page).

📘
Related Resources

Parameter Overview: Understand how to choose and format parameters for your request use case.

Entity Type Parameter Guide: View parameters sorted by supported filter.type instead.

Parameter Name	Type	Description	Compatible Entity Types
`filter.address`	string	Filter by address using a partial string match. Supports comma-separated terms.	Place
`filter.audience.types`	array of strings	Filter by a list of audience types.
`filter.content_rating`	string	Filter by a comma-separated list of content ratings based on the MPAA film rating system, which determines suitability for various audiences.	Movie, TV Show
`filter.date_of_birth.max`	string, YYYY-MM-DD	Filter by the most recent date of birth desired for the queried person.	Person
`filter.date_of_birth.min`	string, YYYY-MM-DD	Filter by the earliest date of birth desired for the queried person.	Person
`filter.date_of_death.max`	string, YYYY-MM-DD	Filter by the most recent date of death desired for the queried person.	Person
`filter.date_of_death.min`	string, YYYY-MM-DD	Filter by the earliest date of death desired for the queried person.	Person
`filter.dimensions.hotel_class`	array of integers	Restricts the `hotel_class` heatmap dimension to specified hotel classes from 1–5. When set, the dimension score reflects the proportion of hotels in the selected classes and adds `hotel_class_count_affinity_rank` and `hotel_class_count_affinity` to the response. Requires `hotel_class` in `heatmap.dimensions`.	Heatmap
`filter.dimensions.price_level`	array of integers	Restricts the `price_level` heatmap dimension to specified price tiers from 1–4. When set, the dimension score reflects the proportion of places at the selected price levels and adds `price_level_count_affinity_rank` and `price_level_count_affinity` to the response. Requires `price_level` in `heatmap.dimensions`.	Heatmap
`filter.entities`	string	Filter by a comma-separated list of entity IDs. Often used to assess the affinity of an entity towards input.	`filter.entity_ids`
`filter.exclude.entities`	string	A comma-separated list of entity IDs to remove from the results.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`filter.exclude.entities.query`		This parameter can only be supplied when using POST HTTP method, since it requires JSON encoded body. The value for `filter.exclude.entities.query` is a JSON array with objects containing the `name` and `address` properties. For a fuzzier search, just include an array of strings. When supplied, it overwrites the `filter.exclude.entities` object with resolved entity IDs. The response will contain a path `query.entities.exclude`, with partial Qloo entities that were matched by the query. If no entities are found, the API will throw a `400` error.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`filter.exclude.tags`	string	Exclude entities associated with a comma-separated list of tags.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`operator.exclude.tags`	string	Specifies how multiple `filter.exclude.tags` values are combined in the query. Use "union" (equivalent to a logical "or") to exclude results that contain at least one of the specified tags, or "intersection" (equivalent to a logical "and") to exclude only results that contain all specified tags. The default is "union".	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`filter.external.exists`	string	Filter by a comma-separated list of external keys. (`resy`\|`michelin`\|`tablet`).	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`operator.filter.external.exists`	string	Specifies how multiple `filter.external.exists` values are combined in the query. Use "union" (equivalent to a logical "or") to return results that match at least one of the specified external keys (e.g., resy, michelin, or tablet), or "intersection" (equivalent to a logical "and") to return only results that match all specified external keys. The default is "union".	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`filter.external.resy.count.max`	integer	Filter places to include only those with a Resy rating count less than or equal to the specified maximum. Applies only to entities with `filter.type` of `urn:entity:place`.
`filter.external.resy.count.min`	integer	Filter places to include only those with a Resy rating count greater than or equal to the specified minimum. Applies only to entities with `filter.type` of `urn:entity:place`.
`filter.external.resy.party_size.max`	integer	Filter by the maximum supported party size required for a Point of Interest.
`filter.external.resy.party_size.min`	integer	Filter by the minimum supported party size required for a Point of Interest.
`filter.external.resy.rating.max`	float	Filter places to include only those with a Resy rating less than or equal to the specified maximum (1–5 scale). Applies only to entities with `filter.type` of `urn:entity:place`.
`filter.external.resy.rating.min`	float	Filter places to include only those with a Resy rating greater than or equal to the specified minimum (1–5 scale). Applies only to entities with `filter.type` of `urn:entity:place`.
`filter.external.tripadvisor.rating.count.max`	integer	Filter places to include only those with a Tripadvisor review count less than or equal to the specified maximum. This filter only applies to entities with `filter.type` of `urn:entity:place`.	Place
`filter.external.tripadvisor.rating.count.min`	integer	Filter places to include only those with a Tripadvisor review count greater than or equal to the specified minimum. This filter only applies to entities with `filter.type` of `urn:entity:place`.	Place
`filter.external.tripadvisor.rating.max`	float	Filter places to include only those with a Tripadvisor rating less than or equal to the specified maximum. This filter only applies to entities with `filter.type` of `urn:entity:place`.	Place
`filter.external.tripadvisor.rating.min`	float	Filter places to include only those with a Tripadvisor rating greater than or equal to the specified minimum. This filter only applies to entities with `filter.type` of `urn:entity:place`.	Place
`filter.finale_year.max`	integer	Filter by the latest desired year for the final season of a TV show.	TV Show
`filter.finale_year.min`	integer	Filter by the earliest desired year for the final season of a TV show.	TV Show
`filter.gender`	string	Filter results to align with a specific gender identity. Used to personalize output based on known or inferred gender preferences.	Person
`filter.geocode.admin1_region`	string	Filter by `properties.geocode.admin1_region`. Exact match (usually state).	Destination, Place
`filter.geocode.admin2_region`	string	Filter by `properties.geocode.admin2_region`. Exact match (often county or borough).	Destination, Place
`filter.geocode.country_code`	string	Filter by `properties.geocode.country_code`. Exact match (two-letter country code).	Destination, Place
`filter.geocode.name`	string	Filter by `properties.geocode.name`. Exact match (usually city or town name).	Destination, Place
`filter.hotel_class.max`	integer	Filter by the maximum desired hotel class (1-5, inclusive).	Place
`filter.hotel_class.min`	integer	Filter by the minimum desired hotel class (1-5, inclusive).	Place
`filter.hours`	string	Filter by the day of the week the Point of Interest must be open (Monday, Tuesday, etc.).	Place
`filter.ids`	string	Filter by a comma-separated list of audience IDs.
`filter.latest_known_year.max`	integer	Filter by a certain maximum year that shows were released or updated.	TV Show
`filter.latest_known_year.min`	integer	Filter by a certain minimum year that shows were released or updated.	TV Show
`filter.location`	string	Filter by a WKT `POINT`, `POLYGON`, `MULTIPOLYGON` or a single Qloo ID for a named `urn:entity:locality`. WKT is formatted as X then Y, therefore longitude is first (`POINT(-73.99823 40.722668)`). If a Qloo ID or WKT `POLYGON` is passed, `filter.location.radius` will create a <glossary:fuzzy> boundary when set to a value > 0.	Destination, Place
`filter.exclude.location`	string	Exclude results that fall within a specific location, defined by either a WKT `POINT`, `POLYGON`, `MULTIPOLYGON`, or a Qloo ID for a named `urn:entity:locality`. WKT is formatted with longitude first (e.g., `POINT(-73.99823 40.722668)`). When using a locality ID or a WKT `POLYGON`, setting `filter.location.radius` to a value > 0 creates a fuzzy exclusion boundary.	Destination, Place
`filter.location.query`	string	A query used to search for one or more named `urn:entity:locality` Qloo IDs for filtering requests, equivalent to passing the same Locality Qloo ID(s) into `filter.location`. For GET requests: Provide a single locality query as a string. For POST requests: You can still send a single locality as a string. Or you can send an array of locality names to query multiple localities at once. When multiple localities are provided, their geographic shapes are merged, and the system returns results with the highest affinities across the combined area.Locality queries are fuzzy-matched and case-insensitive. Examples include `New York City`, `Garden City`, `New York`, `Los Angeles`, `Lower East Side`, and AKAs like `The Big Apple`. When a single locality is supplied, the response JSON includes `query.locality.signal` with the matched Qloo entity. If multiple are supplied, this field is omitted. By default, the API includes a tuning that also captures nearby entities just outside the official boundaries of the locality. To turn this off and limit results strictly to within the locality, set `filter.location.radius=0`. If no localities are found, the API returns a 400 error.	Destination, Place
`filter.exclude.location.query`	string	Exclude results that fall within a specific location, defined by either a WKT `POINT`, `POLYGON`, `MULTIPOLYGON`, or a Qloo ID for a named `urn:entity:locality`. WKT is formatted with longitude first (e.g., `POINT(-73.99823 40.722668)`). When using a locality ID or a WKT `POLYGON`, setting `filter.location.radius` to a value > 0 creates a fuzzy exclusion boundary.	Destination, Place
`filter.location.geohash`	string	Filter by a geohash. Geohashes are generated using the Python package pygeohash with a precision of 12 characters. This parameter returns all POIs that start with the specified geohash. For example, supplying `dr5rs` would allow returning the geohash `dr5rsjk4sr2w`.	Destination, Place
`filter.exclude.location.geohash`	string	Exclude all entities whose geohash starts with the specified prefix. Geohashes are generated using the Python package `pygeohash` with a precision of 12 characters. For example, supplying `dr5rs` would exclude any result whose geohash begins with `dr5rs`, such as `dr5rsjk4sr2w`.	Destination, Place
`filter.location.radius`	integer	Filter by the radius (in meters) when also supplying `filter.location` or `filter.location.query`. When this parameter is not provided, the API applies a default tuning that slightly expands the locality boundary to include nearby entities outside its official shape. To disable this behavior and strictly limit results to entities inside the defined locality boundary, set `filter.location.radius=0`.	Destination, Place
`filter.parents.types`	array of strings	Filter by a comma-separated list of parental entity types (`urn:entity:place`). Each type must match exactly.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`filter.popularity.max`	number	Filter by the maximum popularity percentile a Point of Interest must have (float, between 0 and 1; closer to 1 indicates higher popularity, e.g., 0.98 for the 98th percentile).	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`filter.popularity.min`	number	Filter by the minimum popularity percentile required for a Point of Interest (float, between 0 and 1; closer to 1 indicates higher popularity, e.g., 0.98 for the 98th percentile).	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`filter.price_level.max`	integer	Filter by the maximum price level a restaurant can have. Accepts values 1–4, where higher numbers indicate more expensive restaurants (similar to dollar signs). Applies only to Places entities.	Place
`filter.price_level.min`	integer	Filter by the minimum price level a restaurant can have. Accepts values 1–4, where higher numbers indicate more expensive restaurants (similar to dollar signs). Applies only to Places entities.	Place
`filter.price_range.max`	integer	Filter by the maximum price in the desired hotel price range. Accepts an integer between 0 and 1,000,000. Applies only to Places entities.	Place
`filter.price_range.min`	integer	Filter by the minimum price in the desired hotel price range. Accepts an integer between 0 and 1,000,000. Applies only to Places entities.	Place
`filter.properties.business_rating.max`	float	Filter by the highest desired business rating.	Place
`filter.properties.business_rating.min`	float	Filter by the lowest desired business rating.	Place
`filter.publication_year.max`	number	Filter by the latest desired year of initial publication for the work.	Book
`filter.publication_year.min`	number	Filter by the earliest desired year of initial publication for the work.	Book
`filter.rating.max`	number	Filter by the maximum Qloo rating a Point of Interest must have (float, between 0 and 5).	Movie, TV Show
`filter.rating.min`	number	Filter by the minimum Qloo rating a Point of Interest must have (float, between 0 and 5).	Movie, TV Show
`filter.references_brand`	array of strings	Filter by a comma-separated list of brand entity IDs. Use this to narrow down place recommendations to specific brands. For example, to include only Walmart stores, pass the Walmart brand ID. Each ID must match exactly.	Place
`filter.release_country`	array of strings	Filter by a list of countries where a movie or TV show was originally released.	Movie, TV Show
`filter.results.entities`		Filter by a comma-separated list of entity IDs. Often used to assess the affinity of an entity towards input.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`filter.results.entities.query`		Search for one or more entities by name to use as filters. For GET requests: Provide a single entity name as a string. For POST requests: You can provide a single name or an array of names.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`operator.filter.release_country`	string	Specifies how multiple `filter.release_country` values are combined in the query. Use "union" (equivalent to a logical "or") to return results that match at least one of the specified countries, or "intersection" (equivalent to a logical "and") to return only results that match all specified countries. The default is "union".	Movie, TV Show
`filter.release_date.max`	string, YYYY-MM-DD	Filter by the latest desired release date.
`filter.release_date.min`	string, YYYY-MM-DD	Filter by the earliest desired release date.
`filter.release_year.max`	integer	Filter by the latest desired release year.	Movie, TV Show
`filter.release_year.min`	integer	Filter by the earliest desired release year.	Movie, TV Show
`filter.tag.types`	array of strings	Filter by a comma-separated list of audience types. Each audience type requires an exact match. You can retrieve a complete list of audience types via the v2/audiences/types route.
`filter.tags`	string	Filter by a comma-separated list of tag IDs (urn:tag:genre:restaurant:Italian).	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`operator.filter.tags`	string	Specifies how multiple `filter.tags` values are combined in the query. Use "union" (equivalent to a logical "or") to return results that match at least one of the specified tags, or "intersection" (equivalent to a logical "and") to return only results that match all specified tags. The default is "union".	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`filter.type`	string	Filter by the <<glossary:entity type>> to return (urn:entity:place).	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game

Parameter Name	Type	Description	Compatible Entity Types
`bias.trends`	string	The level of impact a trending entity has on the results. Supported by select categories only.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`bias.quality`	number or string	Adds a quality-based contribution to place ranking. Accepts a positive number or weight string (`low`, `medium`, or `high`). Composes with `sort_by=quality`; when both are set, `sort_by=quality` controls ordering. Places without a quality score are filtered out. Applies only when `filter.type=urn:entity:place`.	Place
`signal.demographics.audiences`	array of strings	A comma-separated list of audiences that influence the affinity score. Audience IDs can be retrieved via the v2/audiences search route.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`signal.demographics.audiences.weight`	string	Specifies the extent to which results should be influenced by the preferences of the chosen audience.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`signal.demographics.age`	string	A comma-separated list of age ranges that influence the affinity score. (24_and_younger \| 25_to_29 \| 30_to_34 \| 35_to_44 \| 45_to_54 \| 55_and_older)	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`signal.demographics.gender`	string	Specifies whether to influence the affinity score based on gender (male\|female).	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`signal.interests.entities`	array of strings	A list of entity IDs that influence the affinity score. You can also include a `weight` property to indicate the strength of influence for each entity. For `GET` requests: Provide a comma-separated list of entity IDs. For `POST` requests, you can either: -- Send the same string of comma-separated values. -- Send an array of objects with `entity` and `weight` properties, such as: `[ { "entity": "urn:entity:movie:inception", "weight": 10 }, { "entity": "urn:entity:movie:interstellar", "weight": 25 } ]` Weights must be greater than 0 and are relative. A weight of 25 means that entity will more heavily influence affinity scores than a weight of 10.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`signal.interests.entities.query`		This parameter can only be supplied when using the POST HTTP method, which requires a JSON-encoded body. The value for `signal.interests.entities.query` is a JSON array containing objects with name and address properties. For a fuzzier search, you can provide an array of strings. When supplied, it overwrites the `signal.interests.entities` object with resolved entity IDs. The response will contain a path, `query.entities.signal`, with partial Qloo entities that were matched by the query. If no entities are found, a 400 error will be thrown by the API. Additionally, you can specify how each signal.interests.entities.query item should resolve. The`resolve_to` property determines whether to resolve to a place, brand, or both. Options are: `self`: Resolves to a place (default behavior if resolve_to is omitted) `urn:reference:brand`: Resolves to the brand. `both`: Resolves to both a place and a brandBehavior: The system will attempt to resolve to a place. If `both` or `urn:reference:brand` is used, it will also pull the brand associated with the resolved place. Resolved entities are returned inside the `response.query` object: --- If `self` or no `resolve_to` option is provided, the resolved place will include an index property pointing to the position of the query in `signal.interests.entities.query`. --- If `urn:reference:brand` is provided and the brand is available, it will be returned with the resolved place's information, with `entity_id` changed to the brand's ID and subtype changed to `urn:entity:brand`. --- If `both` is used, both the place and brand will be included, with their index properties pointing to the same value (using the same query). Warnings: If a place does not resolve, it will be included in `signal.interests.entities.query` warnings as `not_found`. If a place resolves but a requested brand does not, the brand will be added to the warning `could_not_resolve_brand`.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`signal.interests.tags`	string	Allows you to supply a list of tags to influence affinity scores. You can also include a`weight` property that will indicate the strength of influence for each tag in your list. For `GET` requests: Provide a comma-separated list of tag IDs. For `POST` requests, you can either: -- Send the same string of comma-separated values. -- Send an array of objects with "tag" and "weight" properties, such as: `[ { "tag": "urn:tag:genre:media:horror", "weight": 7 }, { "tag": "urn:tag:genre:media:thriller", "weight": 20 } ]` Weights must be greater than 0 and are relative. So, a weight of 20 means that tag will more heavily influence affinity scores than a weight of 7.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`operator.signal.interests.tags`	string	Specifies how multiple `signal.interests.tags` values are combined in the query. Use "union" (equivalent to a logical "or") to return results that contain at least one of the specified tags. In this mode, the tag with the highest affinity is used for scoring. - Use "intersection" (equivalent to a logical "and") or leave this field empty to return results that contain all specified tags, with affinity scores merged across them.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`signal.location`	string	The geolocation to use for geospatial results. The value will be a WKT POINT, POLYGON or a single Qloo ID for a named urn:entity:locality to filter by. WKT is formatted as X then Y, therefore longitude is first (POINT(-73.99823 40.722668)). Unlike `filter.location.radius`, `signal.location.radius` is ignored if a Qloo ID or WKT POLYGON is passed.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`signal.location.query`	string	A string query used to search for a named urn:entity:locality Qloo ID for geospatial results, effectively equivalent to passing the same Locality Qloo ID into `signal.location`. Examples of locality queries include New York City, Garden City, New York, Los Angeles, Lower East Side, and AKAs like The Big Apple. These queries are <glossary:fuzzy>-matched and case-insensitive. When `filter.location.query` is supplied, the response JSON will include `query.locality.signal`, which contains the partially matched Qloo entity. If no locality is found, the API will return a 400 error.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`signal.location.radius`	integer	The optional radius (in meters), used when providing a WKT POINT. We generally recommend avoiding this parameter, as it overrides dynamic density discovery.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game

Parameter Name	Type	Description	Compatible Entity Types
`diversify.by`	string	Limits results by a diversification field before paging. Existing values include `properties.geocode.city` and `properties.geocode.metro`. Use `subtype` with `filter.type=urn:tag` to cap results per tag subtype before paging, using `diversify.take` to set the limit.
`diversify.take`	integer	Sets the maximum number of results to return per city when using `diversify.by: "properties.geocode.city"`. For example, if set to 5, the response will include up to 5 entities with the highest affinities in each city.
`feature.explainability`	boolean	When set to `true`, the response includes explainability metadata for each recommendation and for the overall result set. Per-recommendation: Each result includes a `query.explainability` section showing which input entities (e.g. `signal.interests.entities`) contributed to the recommendation and by how much. Scores are normalized between 0–1. Entities with scores ≥ 0.1 are always included; those below may be omitted to reduce response size. Aggregate impact: The top-level `query.explainability` object shows average influence of each input entity across top-N result subsets (e.g. top 3, 5, 10, all). Note: If explainability cannot be computed for the request, a warning is included under `query.explainability.warning`, but results still return normally.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`offset`	integer	The number of results to skip, starting from 0. Allows arbitrary offsets but is less commonly used than `page`.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`heatmap.dimensions`	array of strings	Adds per-geohash place attributes as additional heatmap response columns. Accepted values are `quality`, `popularity`, `hotel_class`, and `price_level`. Each requested dimension adds `<dim>_affinity_rank` normalized from 0–1 and `<dim>_affinity` percent-rank values. Dimensions also influence the overall `query.affinity` ranking. Applies only when `filter.type=urn:heatmap` and `output.heatmap.boundary=urn:geohash`.	Heatmap
`output.heatmap.boundary`	string	Indicates the type of heatmap output desired: The default is geohashes. The other options are a city or a neighborhood.	Heatmap
`page`	integer	The page number of results to return. This is equivalent to take + offset and is the recommended approach for most use cases.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`sort_by`	string	This parameter modifies the results sorting algorithm. Existing values include `affinity`, `distance`, and `rating`. Use `quality` to order place results by quality score, highest first. When `sort_by=quality` is used, only places with a quality score are returned and `filter.type` must be `urn:entity:place`.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game
`take`	integer	The number of results to return. Default is `20`. The maximum allowed is `50`. To retrieve additional results, use the `page` parameter to access the next page of results. This is the recommended approach for pagination. For specific cases, the `offset` parameter can be used with `take` to skip a set number of results.	Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game