Search and filter products

This endpoint allows querying for product information using several search parameters. Common use cases include the initial and periodic retrieval of products in a certain city or country, retrieving a list of popular products in a given location, or a free-text query.

GET /products

Search and filter products

{"openapi":"3.1.0","info":{"title":"Tiqets Distributor API","version":"2.4.1"},"tags":[{"name":"Content API"}],"servers":[{"url":"https://api-tiqt-test.steq.it/v2","description":"Test Environment"},{"url":"https://api.tiqets.com/v2","description":"Production Environment"}],"paths":{"/products":{"get":{"tags":["Content API"],"summary":"Search and filter products","parameters":[{"$ref":"#/components/parameters/Authorization"},{"name":"city_id","in":"query","required":false,"description":"Only return products located in the defined city.\nUse the [/cities](#tag/Content-API/paths/~1cities/get) endpoint to find the IDs Tiqets has assigned to the various known cities.\nProducts located in the surrounding area can also be returned, this depends on the configuration of each individual product.\n\nRepeat the city_id parameter to broaden the search to span multiple cities.\n","schema":{"type":"integer"},"explode":true},{"name":"city_name","in":"query","required":false,"description":"Name of the city to filter by. Useful for debugging or certain use cases. We recommend using `city_id` instead.","schema":{"type":"string"}},{"name":"country_id","in":"query","required":false,"description":"Tiqets ID of the product country to filter by.","schema":{"type":"integer"}},{"name":"country_name","in":"query","required":false,"description":"Name of the country to filter by. Useful for debugging or certain use cases. We recommend using `country_id` instead.","schema":{"type":"string"}},{"$ref":"#/components/parameters/Currency"},{"name":"exclude_city_id","description":"Exclude products from the results if they belong to the specified city.","in":"query","required":false,"schema":{"type":"integer"},"explode":true},{"name":"exclude_venue_id","description":"Exclude products from the results if they belong to the specified experience.","in":"query","required":false,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/Language"},{"name":"lat","description":"Filters the result set by latitude. Requires a combination of latitude/longitude parameters. Also see `max_distance`.","in":"query","required":false,"schema":{"type":"number"}},{"name":"lng","in":"query","required":false,"description":"Filters the result set by longitude. Requires a combination of latitude/longitude parameters. Also see `max_distance`.","schema":{"type":"number"}},{"name":"max_distance","description":"Maximum distance in kilometers to filter results by. Value can be between 0 and 100; defaults to 5 if undefined.","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"min_rating","description":"Minimum rating of the product in customer reviews.","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":5}},{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/Page"},{"name":"query","description":"Textual query to find products that match the query.\nThe results are ranked by internal calculation of relevancy which can change over time.\nAdding more keywords narrows down the results.\n","in":"query","required":false,"schema":{"type":"string"}},{"name":"require_venue","description":"Define as true if you do not wish to include products that do not have a determined venue location. Defaults to false if undefined.","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"sort","description":"Sort by\n- `popularity`\n- `price`\n- `title`\n- `distance` (in combination with `lat`/`lng`)\n- `score` (Search query matching score. Only in combination with the `query` parameter).\nSort ascending (`asc`) or descending (`desc`).\n","in":"query","required":false,"schema":{"type":"string"},"explode":true},{"name":"tag_id","description":"ID of the tag to filter by. See tags endpoint.\nRepeat the tag_id parameter to broaden the search to include one or more of the provided tag IDs.\n","in":"query","required":false,"schema":{"type":"integer"},"explode":true},{"name":"experience_id","in":"query","required":false,"description":"ID of the experience to filter by.\nExperiences can be searched and retrieved using the dedicated Experiences endpoint.\n\nRepeat the experience_id parameter to broaden the search to span multiple experiences.\n\nNote that this parameter is not allowed together with venue_id that is deprecated.\n","schema":{"type":"integer"},"explode":true},{"name":"venue_id","deprecated":true,"in":"query","required":false,"description":"ID of the experience to filter by.\nExperiences can be searched and retrieved using the dedicated Experiences endpoint.\n\nRepeat the venue_id parameter to broaden the search to span multiple experiences.\n\nNote that this parameter is deprecated and experience_id is recommended. If you specify this and experience_id, it will trigger an error.\n","schema":{"type":"integer"},"explode":true}],"responses":{"200":{"description":"Successful operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"pagination":{"$ref":"#/components/schemas/Pagination"},"products":{"$ref":"#/components/schemas/ProductList"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"parameters":{"Authorization":{"name":"Authorization","in":"header","required":true,"description":"Token <Your_API_Key>.","schema":{"type":"string","default":"Token <Partner_API_key>."}},"Currency":{"name":"currency","in":"query","description":"Currency code of the price components (ISO 4217).","required":false,"style":"form","explode":true,"schema":{"type":"string","default":"EUR"}},"Language":{"name":"lang","in":"query","description":"Language of the content to retrieve (ISO 639-1). Defaults to English if undefined.","required":false,"style":"form","explode":true,"schema":{"type":"string","default":"en"}},"PageSize":{"name":"page_size","in":"query","description":"Number of items per page. Default value is 10, maximum value is 100.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"Page":{"name":"page","in":"query","description":"Number of the page to retrieve. Used in combination with the `page_size` parameter to define the page size.","required":false,"schema":{"type":"integer","minimum":1,"default":1}}},"schemas":{"Pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"page":{"type":"integer","description":"Number of the current page."},"page_size":{"type":"integer","description":"Size of the current page."}}},"ProductList":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"Product":{"type":"object","properties":{"id":{"type":"string","description":"Unique Tiqets ID of the product."},"language":{"description":"Language of the content information as in the request parameter. The format follows ISO 639-1 codes.","type":"string"},"title":{"type":"string","description":"Localized title."},"city_name":{"description":"Localized name of the product city.","type":"string"},"city_id":{"description":"Tiqets ID of the product city.","type":"string"},"country_name":{"description":"Localized name of the product country.","type":"string"},"country_id":{"description":"Tiqets ID of the product country.","type":"string"},"tag_ids":{"description":"List of tag IDs. See tags.","type":"array","items":{"type":"string"}},"images":{"$ref":"#/components/schemas/Images"},"geolocation":{"description":"Dictionary with `lat`, `lng` coordinates of the product.","type":["object","null"],"properties":{"lat":{"type":"number","description":"The latitude of the geographic location."},"lng":{"type":"number","description":"The longitude of the geographic location."}}},"distance":{"description":"Distance in kilometers from the given `lat`, `lng`; displayed when filtering by coordinates.","type":["integer","null"]},"venue":{"description":"The experience object. (Experiences were called venue in the past, hence the object name 'venue'.) Experiences can be searched and retrieved using the dedicated Experiences endpoint.","type":["object","null"],"properties":{"address":{"description":"Street address of the venue (can be accurate or an estimate).","type":["string","null"]},"id":{"description":"Unique Tiqets ID of the experience.","type":"string"},"name":{"description":"Name of the experience.","type":"string"},"postal_code":{"description":"The zip code of the experience.","type":["string","null"]}}},"ratings":{"description":"Ratings object.","type":["object","null"],"properties":{"average":{"description":"Average number of ratings/reviews (1-5 star rating).","type":["number","null"]},"total":{"description":"Total number of ratings/reviews.","type":"integer"}}},"price":{"description":"Retail price on Tiqets.com in the currency as returned by `currency`.","type":["number","null"]},"currency":{"description":"Currency code (ISO 4217) of the price. Follows the currency as defined in the API request. Defaults to EUR if no currency is provided as a request parameter.","type":["string","null"]},"price_in_supplier_currency":{"description":"Retail price on Tiqets.com following the supplier currency as returned by `supplier_currency`.","type":["number","null"]},"supplier_currency":{"description":"Currency code (ISO 4217) of the price in supplier currency.","type":["string","null"]},"product_slug":{"description":"Slug of a product.","type":["string","null"]},"supports_cancellation_insurance_in_affiliate_checkout":{"description":"Indicates whether the product can be bought with cancellation insurance in affiliate checkout.","type":["boolean","null"]},"marketing_restrictions":{"description":"A list of marketing channels that you are not allowed to use with this product. Currently either `things_to_do` or `null`, other channels might be added at any time.","type":["array","null"],"deprecated":true,"items":{"type":"string"}},"marketing_restrictions_detailed":{"description":"A list of marketing channels and corresponding restrictions that apply for this product. New channels might be added at any time.","type":["array","null"],"items":{"type":"object","properties":{"type":{"type":"string","enum":["AD_CONTENT","KEYWORD","TARGETING","THINGS_TO_DO_ADS","THINGS_TO_DO_BOOKING_MODULE"],"description":"The type of marketing activity that is restricted."},"scope":{"type":"string","enum":["COUNTRY","CITY","REGIONS","CITY_COUNTRY_GLOBAL","OTHER","ALL"],"description":"The geographic scope of the restriction."},"languages":{"type":"array","items":{"type":"string"},"description":"List of IETF language codes this restriction applies to, or `ALL` if restriction applies for all languages."},"parameters":{"type":"array","items":{"type":"string"},"description":"Additional parameters for the restriction."},"scope_geolocation":{"type":["string","null"],"description":"Optional geolocation identifier for the scope."}}}},"prediscount_price":{"description":"Pre-discount price returned in case a discount applies to the `price` of this product.","type":["number","null"]},"discount_percentage":{"type":["number","null"],"description":"Percentage of the price discount in case there is a discount applied. Rounded to full per cent."},"display_price":{"deprecated":true,"type":["number","null"],"description":"Deprecated. Please use `price` instead."},"display_booking_fee":{"type":["number","null"],"description":"Booking fee."},"cancellation":{"description":"Cancellation information.","type":["object","null"],"properties":{"window":{"type":["integer","null"],"description":"The cancellation window in hours corresponds to the cancellation policy."},"policy":{"type":"string","enum":["before_timeslot","before_date","never"],"description":"Indicates the cancellation policy of the product.\nPossible values:\n- before_date: Cancellation is possible until X hours (returned as `window`) before midnight on the visit date.\n- before_timeslot: Cancellation is possible until X hours (returned as `window`) before the booked timeslot (if the product makes use of timeslots) or the opening hour of the venue (if the product does not have timeslots).\n- never: Cancellation is not possible for this product."}}},"product_url":{"description":"URL to the product on the Tiqets.com website.\n\nThe field `product_url` points to the consumer Tiqets.com website. An affiliate tracking code is added to the URL to measure usage and track what orders are done by what partner (`?partner=foobar`).\nThe URL does not contain or follow any currency parameter. The currency shown is determined by the configuration of the browser accessing the URL.","type":"string"},"product_checkout_url":{"description":"URL to product checkout on the Tiqets.com website.\n\nThe field `product_checkout_url` points to the consumer Tiqets.com website. An affiliate tracking code is added to the URL to measure usage and track what orders are done by which partner (`?partner=foobar`).\nThe URL does not contain or follow any currency parameter. The currency shown is determined by the configuration of the browser accessing the URL.","type":"string"},"tagline":{"description":"Localized tagline.","type":["string","null"]},"promo_label":{"description":"Promotional label.","type":["string","null"]},"languages":{"type":["array","null"],"description":"List of supported languages to retrieve content information for this product. The format follows ISO 639-1 codes.","items":{"type":"string"}},"sale_status":{"description":"Indicates whether the product is available for sale ('available') or not ('unavailable').","type":["string","null"],"enum":["unavailable","available"]},"sale_status_reason":{"type":["string","null"],"enum":["The product is temporarily not available due to technical reasons","The venue of this product is closed","The product is out of season","The product is temporarily not available"],"description":"If sale_status is 'unavailable' this field indicates the reason why."},"sale_status_expected_reopen":{"type":["string","null"],"format":"date","description":"When a product is temporarily unavailable this field will be present with the expected reopen date."},"summary":{"description":"Localized summary description of the product.","type":["string","null"]},"whats_included":{"description":"Localized list of what is included in the tickets.","type":["string","null"]},"whats_excluded":{"description":"Localized list of what is explicitly not included in the tickets.","type":["string","null"]},"best_time_to_visit":{"deprecated":true,"type":["array","null"],"description":"Replaced with tags.","items":{"type":"string"}},"live_guide_languages":{"description":"List of the languages supported in the live guides (tours). The format generally follows ISO 639-1 codes; for languages that do not have a 639-1 code, it is in 639-3.","type":["array","null"],"items":{"type":"string"}},"audio_guide_languages":{"description":"List of the languages supported for the audio guides. The format generally follows ISO 639-1 codes; for languages that do not have a 639-1 code, it is in 639-3.","type":["array","null"],"items":{"type":"string"}},"language_selection":{"description":"List of the languages the customer needs to select one language from. The format follows ISO 639-3 codes.","type":["array","null"],"items":{"type":"string"}},"starting_time":{"description":"Product activity starting time if the product includes a tour. Format HH:MM:SS.","type":["string","null"]},"timezone":{"type":["string","null"],"description":"Product timezone, following the venue timezone. In tz format."},"duration":{"description":"Product activity estimated duration time. Format HH:MM:SS.","type":["string","null"]},"starting_point":{"description":"Starting point details of the tour, experience or venue.\nAll products have a starting point, regardless of their type.\nFor venues, the starting point simply repeats the venue's address and coordinates.\n","type":["object","null"],"properties":{"lat":{"type":["number","null"],"description":"The latitude of a geographic location."},"lng":{"type":["number","null"],"description":"The longitude of a geographic location."},"address":{"type":["string","null"],"description":"The street address of the venue (can be accurate or an estimate)."},"city_id":{"type":"number","description":"Tiqets ID of the city."},"label":{"type":["string","null"],"description":"The name of the location."}}},"wheelchair_access":{"description":"Indicates the venue's wheelchair accessibility.","type":["boolean","null"]},"skip_line":{"deprecated":true,"description":"Indicates whether the product includes a skip the line feature.","type":["boolean","null"]},"smartphone_ticket":{"description":"Indicates whether the venue supports tickets via smartphone without any printing.","type":["boolean","null"]},"advance_arrival_time":{"description":"Recommended time before the start of the activity that the customer should arrive by. Typically used for security checks (cruises), getting seated (theatre), or checking if everyone is there (tours). Format HH:MM:SS.","type":["string","null"]},"last_admission_window":{"description":"Last ticket admission time before the venue closing time. Format HH:MM:SS.","type":["string","null"]},"description":{"description":"Full product description. Only for partners with special contracts.","type":["string","null"]},"highlights":{"deprecated":true,"description":"Localized highlight description of the product. Only for partners with special contracts.","type":["string","null"]},"safety_measures":{"deprecated":true,"description":"In the past, this object returned safety measures of the venue related to the COVID-19 period. These measures have been deprecated as they are not applicable anymore. This object can be completely ignored and is only returned for compatibility with legacy integrations.","type":["object","null"],"properties":{"cash_accepted":{"description":"Always `null`.","type":["boolean","null"]},"face_mask":{"description":"Always `null`.","type":["string","null"]},"gloves":{"description":"Always `null`.","type":["string","null"]},"has_hand_sanitizer_available":{"description":"Always `false`.","type":["boolean","null"]},"has_intensified_cleaning":{"description":"Always `false`.","type":["boolean","null"]},"has_reduced_capacity":{"description":"Always `false`.","type":["boolean","null"]},"has_social_distancing":{"description":"Always `false`.","type":["boolean","null"]},"has_temperature_checks":{"description":"Always `false`.","type":["boolean","null"]},"limited_duration":{"description":"Always `null`.","type":["string","null"]},"online_ticketing_only":{"description":"Always `false`.","type":["boolean","null"]},"reduced_capacity":{"description":"Always `null`.","type":["integer","null"]},"waiting_time":{"description":"Always `null`.","type":["string","null"]}}},"exhibitions":{"description":"Localized exhibition information scheduled at the venue.","type":["array","null"],"items":{"type":"object","properties":{"from_date":{"type":["string","null"],"description":"Exhibition start date. Format YYYY-MM-DD."},"to_date":{"type":["string","null"],"description":"Exhibition end date. Format YYYY-MM-DD."},"title":{"type":"string","description":"Exhibition title."},"id":{"type":"number","description":"Tiqets ID of the exhibition."},"description":{"type":["string","null"],"description":"Localized exhibition description. All partners receive a short exhibition description. Partners with special contracts receive the full exhibition description."},"url":{"description":"URL to the exhibition page on the Tiqets.com website.\n\nThe field `url` points to the consumer Tiqets.com website. An affiliate tracking code is added to the URL to measure usage and track what orders are done by which partner (`?partner=foobar`).\nThe URL does not contain or follow any currency parameter. The currency shown is determined by the configuration of the browser accessing the URL.","type":["string","null"]}}}},"instant_ticket_delivery":{"description":"Indicates whether the tickets will be delivered automatically in less than 10 minutes. If `false`, the fulfilment can take longer than an hour.","type":["boolean","null"]},"is_package":{"description":"Indicates whether the product is a package. Packages consist of two or more stand-alone products. If the product is a package, the IDs of the included products are returned by `package_products`.","type":"boolean"},"in_packages":{"description":"List of packages that contain this product.","type":["array","null"],"items":{"type":"number"}},"package_products":{"description":"List of products included in the package.","type":["array","null"],"items":{"type":"number"}},"supplier":{"description":"Information about the supplier of the product.","type":["object","null"],"properties":{"name":{"type":"string","description":"Supplier name."},"address":{"type":["string","null"],"description":"Supplier street address."},"city":{"type":["string","null"],"description":"Supplier city."},"postalcode":{"type":["string","null"],"description":"Supplier postal code."},"countrycode":{"type":["string","null"],"description":"Supplier country code (ISO 3166-2)."}}},"product_groups":{"description":"List of product groups this product is part of.","type":["array","null"],"items":{"$ref":"#/components/schemas/ProductGroup"}}}},"Images":{"type":"array","description":"Array of image URLs in different sizes and corresponding image information.","items":{"type":"object","properties":{"small":{"type":"string","description":"URL of small size image."},"medium":{"type":"string","description":"URL of medium size image."},"large":{"type":"string","description":"URL of large size image."},"extra_large":{"type":"string","description":"URL of extra large size image."},"alt_text":{"type":["string","null"],"description":"ALT text for the image. Returned if available for the image in the defined request language. Returned as `null` if no ALT text is available."},"credit":{"type":["string","null"],"description":"Image credit information. Credit needs to be shown when an image is shown on your system. Tiqets cannot be held liable for any infringement."}}}},"ProductGroup":{"type":"object","properties":{"group_id":{"type":"string","description":"ID of the group. Corresponds with the product ID of the main product of the group."},"type":{"type":"string","enum":["booking_sources","upsell","comparison"],"description":"Type of the group."},"products":{"type":"array","description":"List of all products that belong to this group.","items":{"type":"object","properties":{"id":{"type":"string","description":"Product ID."},"title":{"type":"string","description":"Product title."},"currency":{"type":"string","description":"Currency code (ISO 4217) for the existing amounts."},"from_price":{"type":["number","null"],"description":"From price of the product."}}}}}}},"responses":{"BadRequest":{"description":"Bad Request -- Check your request parameters (typo in parameter or invalid value).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"},"field_errors":{"type":"object"}}}}}},"Unauthorized":{"description":"Unauthorized -- Your API key is incorrect.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}}},"Forbidden":{"description":"Forbidden -- The endpoint or parameters are not allowed for the matching API key.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}}},"NotFound":{"description":"Not Found -- Requested resource/endpoint could not be found.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}}},"MethodNotAllowed":{"description":"Method Not Allowed -- Check your request method.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}}},"TooManyRequests":{"description":"Too Many Requests -- We currently apply a fair-use policy, but we might enforce limits in the future.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}}},"InternalServerError":{"description":"Internal Server Error -- We had a problem with our server. Try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}}},"ServiceUnavailable":{"description":"Service Unavailable -- We're temporarily offline for maintenance. Please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}}}}}}