Search and filter experiences¶
The term experience describes a venue, activity, service, point of interest. Tickets for an experience are available through one or more products related to the experience.
This endpoint allows querying for experiences using several search parameters. Common use cases include the initial and periodic retrieval of experiences in a certain city or country, retrieving a list of popular experiences in a given location, or a free-text query.
Read more with our guide how-to-find-and-display-experiences-using-the-tiqets-api
GET /experiences¶
Search and filter experiences
{
"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": {
"/experiences": {
"get": {
"tags": [
"Content API"
],
"summary": "Search and filter experiences",
"parameters": [
{
"$ref": "#/components/parameters/Authorization"
},
{
"name": "city_id",
"in": "query",
"required": false,
"description": "Only return experiences 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.\nExperiences 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",
"explode": true,
"schema": {
"type": "integer"
}
},
{
"name": "country_id",
"in": "query",
"required": false,
"description": "Only return experiences located in the defined country.\nUse the [/countries]#tag/Content-API/paths/~1countries/get) endpoint to find the IDs Tiqets has assigned to the various known countries.\nExperiences located in the surrounding area can also be returned, this depends on the configuration of each individual product.\n\nRepeat the country_id parameter to broaden the search to span multiple countries.\n",
"explode": true,
"schema": {
"type": "integer"
}
},
{
"name": "type",
"in": "query",
"required": false,
"explode": true,
"schema": {
"type": "string",
"enum": [
"venue",
"activity",
"service",
"poi"
]
},
"description": "Only return experiences with the defined type."
},
{
"$ref": "#/components/parameters/Currency"
},
{
"$ref": "#/components/parameters/Language"
},
{
"$ref": "#/components/parameters/PageSize"
},
{
"$ref": "#/components/parameters/Page"
}
],
"responses": {
"200": {
"description": "Successful operation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
},
"experiences": {
"$ref": "#/components/schemas/ExperienceList"
}
}
}
}
}
},
"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."
}
}
},
"ExperienceList": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Experience"
}
},
"Experience": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Unique Tiqets ID of the experience."
},
"type": {
"type": "string",
"description": "Type of the experience. Tiqets currently categorises each experience into one of these four types: activity (e.g. a guided tour), service (e.g. public transport), venue (e.g. a museum), or poi (point of interest).",
"enum": [
"activity",
"service",
"venue",
"poi"
]
},
"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."
},
"images": {
"$ref": "#/components/schemas/Images"
},
"address": {
"description": "Address of the experience.",
"type": "object",
"properties": {
"street": {
"description": "Street and number of the experience.",
"type": [
"string",
"null"
]
},
"postal_code": {
"description": "Postal code of the experience.",
"type": [
"string",
"null"
]
},
"city_id": {
"description": "Tiqets ID of the experience city.",
"type": "integer"
},
"city_name": {
"description": "Localized name of the experience city.",
"type": "string"
},
"country_id": {
"description": "Tiqets ID of the experience country.",
"type": "integer"
},
"country_name": {
"description": "Localized name of the experience country.",
"type": "string"
},
"lat": {
"type": [
"number",
"null"
],
"description": "The latitude of the experience."
},
"lng": {
"type": [
"number",
"null"
],
"description": "The longitude of the experience."
},
"google_place_id": {
"description": "Google Place ID of the experience.",
"type": [
"string",
"null"
]
}
}
},
"tag_ids": {
"description": "List of tag IDs. See tags.",
"type": "array",
"items": {
"type": "integer"
}
},
"product_ids": {
"description": "List of product IDs that belong to the experience.",
"type": "array",
"items": {
"type": "integer"
}
},
"experience_url": {
"description": "URL to the experience on the Tiqets.com website.\n\nThe field `experience_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"
},
"ratings": {
"description": "Ratings object.",
"type": "object",
"properties": {
"average": {
"description": "Average number of ratings/reviews (1-5 star rating).",
"type": "number"
},
"total": {
"description": "Total number of ratings/reviews.",
"type": "integer"
}
}
},
"currency": {
"type": [
"string",
"null"
],
"description": "Currency code (ISO 4217) of the price. Defaults to EUR if no currency is provided as request parameter."
},
"from_price": {
"type": [
"number",
"null"
],
"description": "From price of the experience."
},
"tagline": {
"type": "string",
"description": "Localized tagline."
},
"description": {
"type": [
"string",
"null"
],
"description": "Experience description."
}
}
},
"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."
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
}