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).
- Parameter Overview: Understand how to choose and format parameters for your request use case.
- Entity Type Parameter Guide: View parameters sorted by supported
filter.typeinstead.
| 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.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 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 entity type to return (urn:entity:place). | Artist, Book, Brand, Destination, Movie, Person, Place, Podcast, TV Show, Video Game |