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

## Attractions by countries

> *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](/demand/docs/open-api/3.2-beta/demand-api/commonlocations/common/locations/countries).
2. Include the returned country codes in the `countries` field.
3. Specify the travel dates and currency.
  * Optionally use `sort.by` "most_popular".


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

## Search by city

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](/demand/docs/open-api/3.2-beta/demand-api/commonlocations/common/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**

```json
{
  "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"
  }
}
```

## Search by attraction IDs

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


Use the `attractions` field to request specific products directly.

**Example:**

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

You can include up to 100 attraction IDs per request.

## Search by coordinates (geo-based)

> *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](/demand/docs/open-api/3.2-beta/demand-api/commonlocations/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.


```json
{
  "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"
  }
}
}
```

### Search with filters

Use filters to refine results and surface more relevant experiences.

Supported filters include:

* Minimum review score.
* Minimum review count.
* Supported languages.


**Example:**

```json
{
  "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"
  }
}
```

### Sorting results

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

Supported values include:

| Sort option | Description |
|  --- | --- |
| `most_popular` | Orders products based on the highest number of reservations in the last 30 days. |
| `highest_review_score` | Shows products with the highest average review score first. |
| `highest_weighted_review_score` | Orders products by a weighted review score based on rating and review volume. |
| `lowest_price_first` | Displays products with the lowest available price first. |
| `nearest_location` | When using the `coordinates` search criterion, it displays products closest to the provided search coordinates first. |
| `trending` | Orders products based on predicted popularity using machine learning signals. |


## Best practices

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


Curious to know more?
- For more information on setting up search requests, explore the [Search for attractions](/demand/docs/attractions/search-attractions) section.
- Refer to the [Pagination guide](/demand/docs/development-guide/pagination) for more details.