Search for Attractions - use cases Beta

Explore common ways to search for attractions and experiences using the Demand API.

Use the /attractions/search endpoint to retrieve attractions, activities, and experiences based on a location, travel dates, and optional filters.

This guide provides examples for common search scenarios.

A valid search request must include:

• Exactly one search criterion: attractions, cities, countries, or coordinates.
• A currency.
• A start and end date.

Both start_date and end_date must be within 180 days of the request date, and the period between start_date and end_date cannot exceed 90 days. The dates can be the same for a single-day search.

You can also use filters, rows, and sort to refine and order the results.

Use country codes to search for attractions located in one or more countries.

1. Obtain the country codes from the /common/locations/countries endpoint.
2. Include the country codes in the countries array.
3. Specify the travel dates and currency.
4. Optionally use sort.by to order the results.

A partner wants to show attractions in the Netherlands and Belgium during a traveller’s trip across both countries.

{
  "currency": "EUR",
  "countries": ["nl", "be"],
  "dates": {
    "start_date": "2026-10-18",
    "end_date": "2026-10-20"
  },
  "rows": 20,
  "sort": {
    "by": "most_popular"
  }
}

Use city IDs to search for attractions located in one or more cities.

This is the most common use case when travellers browse activities in a destination.

A couple looking for attractions in Amsterdam that support Spanish or French.

1. Obtain Amsterdam id from the /common/locations/cities endpoint.
2. Include the city identifier in the cities array.
3. Specify the travel dates and currency.
4. Optionally add filters such as supported languages.

Example request

{
  "currency": "EUR",
  "cities": [-2140479],
  "dates": {
    "start_date": "2026-11-18",
    "end_date": "2026-11-20"
  },
  "filters": {
    "supported_languages": ["es", "fr"]
  },
  "sort": {
    "by": "most_popular"
  }
}

Use the attractions array to search for specific attractions by their IDs.

This is useful when you have previously stored attraction IDs and want to retrieve their current availability and prices.

Example:

{
  "currency": "EUR",
  "attractions": [
    "PR0dwCIbnsiU",
    "AFd2wcIjMauX"
  ],
  "dates": {
    "start_date": "2026-11-18",
    "end_date": "2026-11-20"
  }
}

A business traveller arriving at Amsterdam Central Station wants to find nearby attractions..

Use coordinates to search for attractions near a specific geographic location. The coordinates object must include:

• latitude, between -90 and 90.
• longitude, between -180 and 180.

You can optionally provide radius to define the maximum search distance in kilometres. The default radius is 10 kilometres, and the value must be positive.

1. Call /common/locations/landmarks with Amsterdam's city id (-2140479) to retrieve landmark coordinates.
2. Identify the coordinates of Amsterdam Central Station.
3. Set the returned coordinates (latitude and longitude of Amsterdam Central Station)
4. Set the radius to 1 (in kilometers) to limit the search area.
5. Sort the results by nearest_location, to prioritise attractions closest to the station.

{
  "currency": "EUR",
  "coordinates": {
    "latitude": 52.3791,
    "longitude": 4.9003,
    "radius": 1
  },
  "dates": {
    "start_date": "2026-10-18",
    "end_date": "2026-10-20"
  },
  "sort": {
    "by": "nearest_location"
  }
}

Use filters to refine the search results.

Supported filters include:

• Attraction categories.
• Minimum review score.
• Minimum review count.
• Supported languages.

You can combine multiple filters in the same request.

Use filters.categories to filter results by one or more attraction category IDs.

• Call the /attractions/constants endpoint to retrieve the available category IDs and their localised names.
• You can use both root categories and subcategories as filter values.

Only attractions matching at least one of the selected categories are returned.

If an invalid or unsupported category ID is provided, the search response contains no results.

Example:

{
  "currency": "EUR",
  "cities": [-2140479],
  "dates": {
    "start_date": "2026-11-18",
    "end_date": "2026-11-20"
  },
  "filters": {
    "categories": [
      "PTCMCuXtHgrC",
      "PTCMCY1Fkppn"
    ]
  }
}

Use filters.rating to filter attractions by guest review score and review count.

Example:

{
  "currency": "EUR",
  "countries": ["nl"],
  "dates": {
    "start_date": "2026-11-18",
    "end_date": "2026-11-20"
  },
  "filters": {
    "rating": {
      "minimum_review_score": 4.2,
      "minimum_review_count": 100
    }
  }
}

Use filters.supported_languages to filter results by the languages supported by the attraction.

Values must use lowercase IETF language tags, such as:

• en
• es
• nl
• en-us

To retrieve the complete list of supported languages, call the /common/languages endpoint in the same Demand API version.

Example:

{
  "currency": "EUR",
  "cities": [-2140479],
  "dates": {
    "start_date": "2026-11-18",
    "end_date": "2026-11-20"
  },
  "filters": {
    "supported_languages": ["en", "es", "fr", "de"]
  }
}

You can combine categories, review criteria, and supported languages in the same request.

{
  "currency": "EUR",
  "cities": [-2140479],
  "dates": {
    "start_date": "2026-10-18",
    "end_date": "2026-10-20"
  },
  "filters": {
    "categories": ["PTCMCuXtHgrC"],
    "rating": {
      "minimum_review_score": 4.0,
      "minimum_review_count": 50
    },
    "supported_languages": ["en", "de"]
  }
}

• Use rows to define the number of results returned per page.
• Use page to retrieve the next page of results. On the first request, omit page. For subsequent requests, use the token returned in metadata.next_page.

Use sort.by to control the order of the results.

Example:

{
  "currency": "EUR",
  "cities": [-2140479],
  "dates": {
    "start_date": "2026-10-18",
    "end_date": "2026-10-20"
  },
  "rows": 50,
  "sort": {
    "by": "lowest_price_first"
  }
}

The response contains:

• A list of matching attractions.
• Pagination metadata.
• A unique request identifier.

Each attraction can include:

• The attraction ID.
• Whether free cancellation is available.
• The cheapest available adult price.
• URLs for the attraction details page and search results page.

Example response:

{
  "data": [
    {
      "id": "PRahAzWtTraa",
      "free_cancellation": true,
      "price": {
        "currency": "EUR",
        "total": 20
      },
      "urls": {
        "app": {
          "detail": "booking://attractions/product?slug=prahazwttraa-heineken-experience-amsterdam&aid=956509",
          "search_results": "booking://attractions/searchresults?ufi=-2140479&pinned_product_id=PRahAzWtTraa&aid=956509"
        },
        "web": {
          "detail": "https://www.booking.com/attractions/nl/prahazwttraa-heineken-experience-amsterdam.en-gb.html?selected_currency=EUR&aid=956509",
          "search_results": "https://www.booking.com/attractions/searchresults/nl/amsterdam.en-gb.html?pinned_product=PRahAzWtTraa&aid=956509"
        }
      }
    },
    {
      "id": "PRAmdacCwQLH",
      "free_cancellation": false,
      "price": {
        "currency": "EUR",
        "total": 15.5
      },
      "urls": {
        "app": {
          "detail": "booking://attractions/product?slug=pramdaccwqlh-madame-tussauds-ticket&aid=956509",
          "search_results": "booking://attractions/searchresults?ufi=-2140479&pinned_product_id=PRAmdacCwQLH&aid=956509"
        },
        "web": {
          "detail": "https://www.booking.com/attractions/nl/pramdaccwqlh-madame-tussauds-ticket.en-gb.html?selected_currency=EUR&aid=956509",
          "search_results": "https://www.booking.com/attractions/searchresults/nl/amsterdam.en-gb.html?pinned_product=PRAmdacCwQLH&aid=956509"
        }
      }
    }
  ],
  "metadata": {
    "next_page": "eyJhbGciOiJIUzI1NiJ9...",
    "total_results": 128
  },
  "request_id": "01fr9ez700exycb98w90w5r9sh"
}

If the response does not contain any attractions:

• Verify that the requested dates have available inventory.
• Check whether the filters are too restrictive.
• Confirm that the attraction, city, or country IDs are valid.
• If you used coordinates, check that the latitude, longitude, and radius values are valid.

If necessary, broaden the search criteria or temporarily remove filters.

✅ Use pagination (rows and metadata.next_page) to handle large result sets.

✅ Use coordinates search together with nearest_location for hyperlocal recommendations.

✅ Combine filters and sorting to surface the most relevant results.

✅ Always include the Affiliate ID header to ensure correct attribution.