# Search attractions

Use this endpoint to search for attractions based on a single search criterion, such as attraction IDs, cities, countries, or geographic coordinates.

Endpoint: POST /attractions/search
Version: 3.2-Beta
Security: BearerAuth

## Header parameters:

  - `X-Affiliate-Id` (integer, required)
    Include here your Affiliate identifier number

## Request fields (application/json):

  - `body` (Search by Attractions (object) or Search by Cities (object) or Search by Countries (object) or Search by Coordinates (object)) — one of:
    - Search by Attractions:
      - `attractions` (array, required)
        List of attraction IDs to search for. When provided, results are limited to these specific attractions.
      - `cities` (array)
        Search for attractions located in one or more cities. Use city IDs obtained from [/common/location/cities](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities)
      - `coordinates` (object)
        Geographic coordinates used to search for attractions near a specific location.
      - `coordinates.latitude` (number, required)
        Latitude of the location.
        Example: 52.3676
      - `coordinates.longitude` (number, required)
        Longitude of the location.
        Example: 4.9041
      - `coordinates.radius` (number)
        Maximum distance in kilometers from the specified coordinates. Defaults to 10 km if not provided.
      - `countries` (array)
        Search for attractions located in one or more countries. Use ISO 3166-1 alpha-2 country codes obtained from [/common/locations/countries](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries)
        Example: ["nl"]
      - `currency` (string, required)
        A three-letter ISO 4217 currency code that defines the currency used for pricing in the response, for example: EUR or USD. n/See common/payments/currencies for the full list of supported currencies.
      - `dates` (object, required)
        Date range used to search for attraction availability.
      - `dates.start_date` (string, required)
        Start date of the availability period, in ISO 8601 date format (YYYY-MM-DD).
      - `dates.end_date` (string, required)
        End date of the availability period, in ISO 8601 date format (YYYY-MM-DD). Can be the same as start_date for single-day attractions.
      - `filters` (object)
        Optional filters to narrow down attraction search results.
      - `filters.rating` (object)
        Filters based on guest review ratings.
      - `filters.rating.minimum_review_score` (number)
        Minimum average guest review score, on a scale from 0 to 5.
      - `filters.rating.minimum_review_count` (integer)
        Minimum number of guest reviews required for an attraction to be included.
      - `filters.supported_languages` (array)
        Filter results by supported languages. Uses [IETF language tag codes](https://en.wikipedia.org/wiki/IETF_language_tag) in lowercase, for example "nl" for Dutch/Nederlands or "en-us" for English (US). To retrieve the full list of supported languages, call the /common/languages endpoint in the same Demand API version you are using.
      - `filters.categories` (array)
        Filter results by one or more attraction category IDs. Only attractions that match at least one of the specified categories are returned. If an invalid or unsupported category ID is provided, the search response will contain no results.
        Enum: "PTTV32SGqJEv", "PTTV3YDywxmN", "PTTV3bWrrud5", "PTTV3cuXCgPo", "PTTV3jCHmADM", "PTTV3t1Fvjp9", "PTTV3y2qdlBL"
      - `page` (string)
        Pagination token used to retrieve the next page of results. Omit this parameter on the first request and use the value returned in metadata.next_page for subsequent pages.
      - `rows` (integer)
        The maximum number of results to return.
      - `sort` (object)
        Sorting options that control the order of the search results.
      - `sort.by` (string)
        Defines how the search results are sorted.
        Enum: "highest_review_score", "highest_weighted_review_score", "lowest_price_first", "most_popular", "nearest_location", "trending"
    - Search by Cities:
      - `attractions` (array)
        List of attraction IDs to search for. When provided, results are limited to these specific attractions.
      - `cities` (array, required)
        Search for attractions located in one or more cities. Use city IDs obtained from [/common/location/cities](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities)
      - `coordinates` (object)
        Geographic coordinates used to search for attractions near a specific location.
      - `coordinates.latitude` (number, required)
        Latitude of the location.
        Example: 52.3676
      - `coordinates.longitude` (number, required)
        Longitude of the location.
        Example: 4.9041
      - `coordinates.radius` (number)
        Maximum distance in kilometers from the specified coordinates. Defaults to 10 km if not provided.
      - `countries` (array)
        Search for attractions located in one or more countries. Use ISO 3166-1 alpha-2 country codes obtained from [/common/locations/countries](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries)
        Example: ["nl"]
      - `currency` (string, required)
        A three-letter ISO 4217 currency code that defines the currency used for pricing in the response, for example: EUR or USD. n/See common/payments/currencies for the full list of supported currencies.
      - `dates` (object, required)
        Date range used to search for attraction availability.
      - `dates.start_date` (string, required)
        Start date of the availability period, in ISO 8601 date format (YYYY-MM-DD).
      - `dates.end_date` (string, required)
        End date of the availability period, in ISO 8601 date format (YYYY-MM-DD). Can be the same as start_date for single-day attractions.
      - `filters` (object)
        Optional filters to narrow down attraction search results.
      - `filters.rating` (object)
        Filters based on guest review ratings.
      - `filters.rating.minimum_review_score` (number)
        Minimum average guest review score, on a scale from 0 to 5.
      - `filters.rating.minimum_review_count` (integer)
        Minimum number of guest reviews required for an attraction to be included.
      - `filters.supported_languages` (array)
        Filter results by supported languages. Uses [IETF language tag codes](https://en.wikipedia.org/wiki/IETF_language_tag) in lowercase, for example "nl" for Dutch/Nederlands or "en-us" for English (US). To retrieve the full list of supported languages, call the /common/languages endpoint in the same Demand API version you are using.
      - `filters.categories` (array)
        Filter results by one or more attraction category IDs. Only attractions that match at least one of the specified categories are returned. If an invalid or unsupported category ID is provided, the search response will contain no results.
        Enum: same as `filters.categories` in "Search by Attractions" (7 values)
      - `page` (string)
        Pagination token used to retrieve the next page of results. Omit this parameter on the first request and use the value returned in metadata.next_page for subsequent pages.
      - `rows` (integer)
        The maximum number of results to return.
      - `sort` (object)
        Sorting options that control the order of the search results.
      - `sort.by` (string)
        Defines how the search results are sorted.
        Enum: same as `sort.by` in "Search by Attractions" (6 values)
    - Search by Countries:
      - `attractions` (array)
        List of attraction IDs to search for. When provided, results are limited to these specific attractions.
      - `cities` (array)
        Search for attractions located in one or more cities. Use city IDs obtained from [/common/location/cities](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities)
      - `coordinates` (object)
        Geographic coordinates used to search for attractions near a specific location.
      - `coordinates.latitude` (number, required)
        Latitude of the location.
        Example: 52.3676
      - `coordinates.longitude` (number, required)
        Longitude of the location.
        Example: 4.9041
      - `coordinates.radius` (number)
        Maximum distance in kilometers from the specified coordinates. Defaults to 10 km if not provided.
      - `countries` (array, required)
        Search for attractions located in one or more countries. Use ISO 3166-1 alpha-2 country codes obtained from [/common/locations/countries](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries)
        Example: ["nl"]
      - `currency` (string, required)
        A three-letter ISO 4217 currency code that defines the currency used for pricing in the response, for example: EUR or USD. n/See common/payments/currencies for the full list of supported currencies.
      - `dates` (object, required)
        Date range used to search for attraction availability.
      - `dates.start_date` (string, required)
        Start date of the availability period, in ISO 8601 date format (YYYY-MM-DD).
      - `dates.end_date` (string, required)
        End date of the availability period, in ISO 8601 date format (YYYY-MM-DD). Can be the same as start_date for single-day attractions.
      - `filters` (object)
        Optional filters to narrow down attraction search results.
      - `filters.rating` (object)
        Filters based on guest review ratings.
      - `filters.rating.minimum_review_score` (number)
        Minimum average guest review score, on a scale from 0 to 5.
      - `filters.rating.minimum_review_count` (integer)
        Minimum number of guest reviews required for an attraction to be included.
      - `filters.supported_languages` (array)
        Filter results by supported languages. Uses [IETF language tag codes](https://en.wikipedia.org/wiki/IETF_language_tag) in lowercase, for example "nl" for Dutch/Nederlands or "en-us" for English (US). To retrieve the full list of supported languages, call the /common/languages endpoint in the same Demand API version you are using.
      - `filters.categories` (array)
        Filter results by one or more attraction category IDs. Only attractions that match at least one of the specified categories are returned. If an invalid or unsupported category ID is provided, the search response will contain no results.
        Enum: same as `filters.categories` in "Search by Attractions" (7 values)
      - `page` (string)
        Pagination token used to retrieve the next page of results. Omit this parameter on the first request and use the value returned in metadata.next_page for subsequent pages.
      - `rows` (integer)
        The maximum number of results to return.
      - `sort` (object)
        Sorting options that control the order of the search results.
      - `sort.by` (string)
        Defines how the search results are sorted.
        Enum: same as `sort.by` in "Search by Attractions" (6 values)
    - Search by Coordinates:
      - `attractions` (array)
        List of attraction IDs to search for. When provided, results are limited to these specific attractions.
      - `cities` (array)
        Search for attractions located in one or more cities. Use city IDs obtained from [/common/location/cities](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities)
      - `coordinates` (object, required)
        Geographic coordinates used to search for attractions near a specific location.
      - `coordinates.latitude` (number, required)
        Latitude of the location.
        Example: 52.3676
      - `coordinates.longitude` (number, required)
        Longitude of the location.
        Example: 4.9041
      - `coordinates.radius` (number)
        Maximum distance in kilometers from the specified coordinates. Defaults to 10 km if not provided.
      - `countries` (array)
        Search for attractions located in one or more countries. Use ISO 3166-1 alpha-2 country codes obtained from [/common/locations/countries](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries)
        Example: ["nl"]
      - `currency` (string, required)
        A three-letter ISO 4217 currency code that defines the currency used for pricing in the response, for example: EUR or USD. n/See common/payments/currencies for the full list of supported currencies.
      - `dates` (object, required)
        Date range used to search for attraction availability.
      - `dates.start_date` (string, required)
        Start date of the availability period, in ISO 8601 date format (YYYY-MM-DD).
      - `dates.end_date` (string, required)
        End date of the availability period, in ISO 8601 date format (YYYY-MM-DD). Can be the same as start_date for single-day attractions.
      - `filters` (object)
        Optional filters to narrow down attraction search results.
      - `filters.rating` (object)
        Filters based on guest review ratings.
      - `filters.rating.minimum_review_score` (number)
        Minimum average guest review score, on a scale from 0 to 5.
      - `filters.rating.minimum_review_count` (integer)
        Minimum number of guest reviews required for an attraction to be included.
      - `filters.supported_languages` (array)
        Filter results by supported languages. Uses [IETF language tag codes](https://en.wikipedia.org/wiki/IETF_language_tag) in lowercase, for example "nl" for Dutch/Nederlands or "en-us" for English (US). To retrieve the full list of supported languages, call the /common/languages endpoint in the same Demand API version you are using.
      - `filters.categories` (array)
        Filter results by one or more attraction category IDs. Only attractions that match at least one of the specified categories are returned. If an invalid or unsupported category ID is provided, the search response will contain no results.
        Enum: same as `filters.categories` in "Search by Attractions" (7 values)
      - `page` (string)
        Pagination token used to retrieve the next page of results. Omit this parameter on the first request and use the value returned in metadata.next_page for subsequent pages.
      - `rows` (integer)
        The maximum number of results to return.
      - `sort` (object)
        Sorting options that control the order of the search results.
      - `sort.by` (string)
        Defines how the search results are sorted.
        Enum: same as `sort.by` in "Search by Attractions" (6 values)

## Response 200 fields (application/json):

  - `data` (array)

  - `data.id` (string)
    Unique identifier of the attraction.

  - `data.free_cancellation` (boolean)
    Indicates whether the attraction offers free cancellation.

  - `data.price` (object)
    Pricing information for the cheapest available adult offer for the attraction.

  - `data.price.currency` (string)
    Currency in which the price is returned.

  - `data.price.total` (number)

  - `data.urls` (object)
    Platform-specific URLs for viewing this item.

  - `data.urls.app` (object)

  - `data.urls.app.detail` (string)
    URL to view the attraction detail page in the app.

  - `data.urls.app.search_results` (string)
    URL to view the attraction within search results in the app.

  - `data.urls.web` (object)

  - `data.urls.web.detail` (string)
    URL to view the attraction detail page on the website.

  - `data.urls.web.search_results` (string)
    URL to view the attraction within the website search results page.

  - `metadata` (object)
    Metadata about the request.

  - `metadata.next_page` (string,null)
    Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter page).

  - `metadata.total_results` (integer)
    The total number of results available.

  - `request_id` (string)
    Uniquely identifies the request. Please provide this identifier when contacting support.