Attractions search - use cases 3.2 Beta

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

Use the /attractions/search endpoint to retrieve available experiences, activities, and tickets for a given location or set of filters.

The examples below show how to structure typical requests for common traveller scenarios.

A search request must include:

• A search criterion (attractions, cities, countries, or coordinates)
• A date range.
• A currency.

Optional parameters such as filters, rows, and sort.by allow you to refine and order the results.

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

1. Obtain the country codes for the Netherlands and Belgium from /common/locations/countries endpoint.
2. Include the returned country codes in the countries field.
3. Specify the travel dates and currency.
   • Optionally use sort.by "most_popular".

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

Use a city ID to return attractions in that area.

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 the Amsterdam id from /locations/cities endpoint.
2. Use the returned city ID (-2140479) as the cities value.
3. Specify dates and optional filters such as supported languages.

Example request

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

A partner already stores attraction IDs and wants to retrieve updated pricing and availability..

Use the attractions field to request specific products directly.

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 latitude and longitude to retrieve nearby attractions.

This approach is ideal for mobile apps or location-based experiences.

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",
  "cities": [
    -2140479, -2154955
  ],
  "coordinates": {
    "latitude": 52.3676,
    "longitude": 4.9041,
    "radius": 1
  },
  "dates": {
    "start_date": "2026-11-18",
    "end_date": "2026-11-20"
  },
  "sort": {
    "by": "nearest_location"
  }
}
}

Use filters to refine results and surface more relevant experiences.

Supported filters include:

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

Example:

{
  "currency": "EUR",
  "cities": [
    -2140479, -2154955
  ],
  "dates": {
    "start_date": "2026-09-18",
    "end_date": "2026-09-20"
  },
  "filters": {
    "rating": {
      "minimum_review_score": 4.2,
      "minimum_review_count": 100
    },
    "supported_languages": [
      "en",
      "es",
      "fr",
      "de"
    ]
  },
  "rows": 50,
  "sort": {
    "by": "most_popular"
  }
}

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

Supported values include:

• 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.