# Filtering and sorting accommodation results

**Learn how to filter and sort accommodations when using the accommodations/search endpoint. This guide explains the supported search filters, their expected values, and how to control the sorting of your search results.**

## Overview

By default,  accommodations/search returns the cheapest available product for each accommodation matching your search criteria.

**Important:** When you apply location filters (e.g., country, region, city), results are sorted by Booking.com popularity (top_picks) in descending order, meaning higher-ranked listings appear first.
You can customise your results using:

* **Filters** – narrow down accommodations based on facilities, amenities, payment options, price, rating, and more.
* **Sorting** – control the order in which results are returned.


## Filters

To apply filters, include specific query parameters in your accommodations/search  request.

See different examples for Demand API version 3.1 and 3.2. Apply the request according to the version of the API you are using.

### Search by accommodation type

You can search for specific type of properties:

* **Hotel**: Standard hotel accommodations.
* **Apartment**: Includes serviced apartments and flats for more home-like stays.
* **Hostel**: Dormitory-style accommodations ideal for budget travellers.
* **Bed and breakfast (B&B)**: Smaller properties offering personalised services.
* **Villa**: Standalone houses or luxury vacation homes.
* **Resort**: Larger properties with various on-site amenities, catering to vacations.
* **Guest house**: Smaller, often family-run, establishments.


You can use one of these filters passing the `accommodations_types` id. For example `204` for hotels, `206` for resorts and, `213` for villas, etc.

→ Get the necessary ids from the [accommodations/constants](/demand/docs/open-api/demand-api/accommodations/accommodations/constants)

#### Example: Search for hotels in Amsterdam

v3.1 example
Include the `accommodation_types` id in the top level request. In this case, for hotels is `[204]`


```json
{
  "accommodation_types": [204],
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "currency": "EUR",
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  },
  "sort": {
    "by": "distance",
    "direction": "descending"
  }
}
```

v3.2 example
If you are using v3.2 of the Demand API, include the `accommodation_types` id under the `"filters"` field.


```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "extras": ["extra_charges", "products"],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "filters": {
    "accommodation_types": [204]
  }
}
```

To include multiple types, list them in the `accommodation_types` array (e.g. ["206", "213"]).

### Search for type of cancellation

You can filter properties by `cancellation_type.free_cancellation`

* `free_cancellation`: Filter accommodations that offer free cancellation up to a certain period before check-in. This is useful for travellers looking for flexibility in case their plans change.
* `no_refundable` (Deprecated)


v3.1 example
Example for `free cancellation`:


```json
{
  "checkin_date": "2026-11-10",
  "checkout_date": "2026-11-15",
  "location": {
    "city": "-2140479"
  },
  "cancellation_type": "free_cancellation",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}
```

v3.2 example 
If you are using v3.2 of the Demand API, include the  `cancellation_type` under the `"filters"`field.


```json
{
  "city": -2140479,
  "booker": {
    "country": "es",
    "platform": "mobile"
  },
  "filters": {"cancellation_type": "free_cancellation"},
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}
```

### Search by accommodation brand

You can specify filters for well-known accommodation chains like "Marriott," "Hilton," "Radisson," or others.

→ Use the [accommodations/chains](/demand/docs/open-api/demand-api/accommodations/accommodations/chains) endpoint with empty body to get the full list of brand ids. Select the one you need for your search request.

v3.1 example
* In this example, "19" represents the "Radisson Hotel Group" brand.
* You can customise this filter to include multiple brands if needed (e.g., "19", "22").



```json

{
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": "-2140479",
  "brands": [
    "19"
  ],
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}
```

v3.2 example 
If you are using v3.2 of the Demand API, include the `brands` ID under the `"filters"` field.


```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "extras": ["extra_charges", "products"],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "filters": {
    "brands": [19]
  }
}
```

Brand filters cannot be combined with specific accommodation IDs but can be used alongside city filters.

### Search by facilities and rating

This filter is based on the availability of facilities in the accommodation.

Some `accommodation_facilities`are:

| 
| `Wi-Fi` | Search for properties that offer free or paid Wi-Fi. |
| `Parking` | Filter for accommodations with available parking facilities. |
| `Pool` | Allows users to search for properties that have swimming pools. |
| `Air conditioning` | Filter based on whether the rooms have air conditioning. |
| `Pet-Friendly` | Locate properties that allow pets. |
| `Kitchen facilities` | Helps to find accommodations with kitchen or kitchenette options. |
| `Fitness center` | Search for accommodations with on-site gym facilities. |
| `Accessibility` | Filters that allow searches for properties with amenities that cater to guests with disabilities. |


→ Get facility IDs from the accommodations/constants endpoint.

Example of search request filtering by:

- Accommodation facilities: parking (2), and restaurant (3).
- Room facilities: air-conditioning (11)


v3.1 example

```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "accommodation_facilities": [2, 3],
  "currency": "EUR",
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "room_facilities": [11],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}
```

v3.2 example 
If you are using v3.2 of the Demand API, include the `accommodation_facilities` IDs and `room_facilities` under the `"filters"` field.


```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "extras": ["extra_charges", "products"],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "filters": {
    "accommodation_facilities": [2, 3],
    "room_facilities": [11]
  }
}
```

Refer to the [accommodations/details guide](/demand/docs/accommodations/look-accommodation-details) for further details on facilities.

### Search for 24h reception accommodation

To retrieve accommodations offering 24h reception service in Amsterdam, you can use the following filter on your search request:

v3.1 example

```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "24_hour_reception": true,
  "currency": "EUR",
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}
```

v3.2 example 
If you are using v3.2 of the Demand API, include the `"24_hour_reception": true` under the `"filters"` field.


```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "extras": ["extra_charges", "products"],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "filters": {
    "24_hour_reception": true
  }
}
```

### Search with payment options

You can restrict results to include properties that support only pay at the property (`pay_at_the_property`) and/or online payments (`pay_online`).

You can apply the payment timing filter in [accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search), [accommodations/availability](/demand/docs/open-api/demand-api/accommodations/accommodations/availability) and [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) requests.

v3.1 example

```json
{
  "coordinates": {
    "latitude": 52.378281,
    "longitude": 4.900070,
    "radius": 100
  },
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "currency": "EUR",
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "extras": [
    "products"
  ],
  "guests": {
    "allocation": [
      {
        "number_of_adults": 2
      }
    ],
    "number_of_rooms": 1,
    "number_of_adults": 2
  },
  "payment": {
    "timing": "pay_at_the_property"
  }
}
```

v3.2 example 
If you are using v3.2 of the Demand API, include the `"payment"` object under the `"filters"` field.


```json
"filters": {
  "payment": {
    "credit_card_required": true,
    "timing": "pay_at_the_property"
  }
}
```

This example returns accommodations that require a credit card and allow pay at the property.

Example in accommodations/details request (applicable to both versions)


```json
{
  "accommodations": [
      10507360
  ],
  "extras": [
    "payment"
  ],
    "payment": {
    "timing": "pay_online"
  }
}
```

See the [Payment timings](/demand/docs/payments/payments-timings) section for more details about online and offline payments.

### Search by minimum or maximum price

Search properties based on their price range using:

| Filters: |  |
|  --- | --- |
| `minimum` | Lower limit price per night. Only accommodations costing more than this specified amount will be returned. |
| `maximum` | Sets an upper limit for the price per night, ensuring that results do not exceed a particular budget.* You can specify both minimum and maximum prices together to define a specific range, such as 100 Eur to 200 Eur per night.
* If specified, will return only results where the price per night falls in the specified range (inclusive).

 |


> Example for accommodation in Amsterdam that cost between 100 Eur and 200 Eur per night, returning the prices in EUR:


v3.1 example

```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "currency": "EUR",
  "price": {
    "minimum": 100,
    "maximum": 200
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}
```

v3.2 example 
If you are using v3.2 of the Demand API, include the `"price"` object under the `"filters"` field.


```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "currency": "EUR",
  "filters": {
    "price": {
      "maximum": "200",
      "minimum": "100"
    }
  }
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}
```

Note
Always include `currency` when using price filters.

### Search by minimum review score

Filter based on guest review score and star ratings.

| Filters: |  |
|  --- | --- |
| `minimum_review_score` | Allows users to specify a minimum review score (from 1 to 10), so that only accommodations meeting the selected score are included in the results. |
| `stars` | Filters properties based on the number of given stars, ensuring that only those with sufficient stars are shown in the range of 1 to 5. |


> *Example: Search for accommodations in Amsterdam (city id -2140479) with a minimum review score of 8 out of 10, and with at least 4 or 5 stars.*


v3.1 example

```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "city": -2140479,
  "rating": {
    "minimum_review_score": 8,
    "stars": [4,5]
  },
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}
```

v3.2 example 
If you are using v3.2 of the Demand API, include the `"rating"` object, `"minimum_review_score"` and `"stars"` values under the `"filters"` field.


```json
"filters": {
  "rating": {
    "minimum_review_score": 8,
    "stars": [4,5]
  }
}
```

The results are sorted to prioritise properties with the highest review scores, helping users quickly find the best-rated accommodations.

### Other filters

There are some other filters such as:

| Filter: | Description |
|  --- | --- |
| `dormitories` | Include or exclude dormitory accommodation. |
| `travel_proud` | For accommodation that is a member of the Booking.com Travel Proud programme. LGBTQ+ friendly properties (Proud Certified). |
| `room_facilities` | It only returns products with rooms that have a specific set of facilities. For example, air conditioning and a balcony. |
| `meal_plan` | Only return products that offer specific meal plans. For example, breakfast included or half-board. |


For a more detailed list of filters check the [API reference](/demand/docs/open-api/demand-api).

## Search by distance

These filters behaviour is the same for both, v3.1 and v3.2 of Demand API.

### Using coordinates

Coordinates parameter helps filtering based on a given latitude, longitude and radius, enabling searches for properties near a particular spot on the map.

You can get the coordinates by using:

* [/locations/landmarks](/demand/docs/open-api/demand-api/commonlocations/common/locations/landmarks) for landmark.
* [/accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details) for an accommodation.
* [/locations/country](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries) for countries.


> *Example: Search for properties within a 5 km radius of the provided latitude and longitude (Amsterdam in this case)*:



```json
{
  "coordinates": {
    "latitude": 52.3676,
    "longitude": 4.9041,
    "radius": 5
  },
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "currency": "EUR",
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}
```

Adjust the latitude, longitude, and radius as needed to search for different areas or distances​.

### Using landmarks

Users can filter accommodations by specifying a distance range from popular landmarks (e.g., airports, museums, etc.)

1. Use the common/locations/landmarks endpoint to get the list of landmarks (and their ids) in a selected city.


**Example: Request for Paris (-1456928):**


```json
{
  "city": -1456928,
  "languages": [
    "en-gb"
  ]
}
```

**Response:**


```json
{
  "request_id": "01jn0p83bec2cyrs2mbn9wwqng",
  "data": [
    {
      "id": 735,
      "name": {
        "en-gb": "Eiffel Tower"
      },
      "coordinates": {
        "latitude": 48.8586,
        "longitude": 2.29398
      }
    },
    {
      "id": 935,
      "name": {
        "en-gb": "Louvre Museum"
      },
      "coordinates": {
        "latitude": 48.86086,
        "longitude": 2.3388
      }
    },
```

1. Include `landmark`and the desired `id` in your search request. In this example: `735` for Eiffel Tower.



```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-15",
  "landmark": 735,
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}
```

Alternatively you can also use specific coordinates.

When including landmark ID, you do not need the city ID.

### Search by location

You can filter by geographic locations using parameters like:

| Fields | Description | Get ids using these endpoints |
|  --- | --- | --- |
| `city`                | To filter by city. | [/location/city](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities) |
| `country` | To filter by country. | [/location/country](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries) |
| `region` | To restrict the search to a specific region inside a country. Example: "725" for Andalusia in "es". | [/location/region](/demand/docs/open-api/demand-api/commonlocations/common/locations/regions) |
| `airport` | To filter by a specific airport. | [/location/airports](/demand/docs/open-api/demand-api/commonlocations/common/locations/airports) |


#### Using city IDs and country codes

These filters can be very handy when looking for accommodations in a specific city/country.

Example of search request:


```json
{
    "booker": {
      "country": "nl",
      "platform": "desktop"
    },
    "checkin": "2026-11-10",
    "checkout": "2026-11-15",
    "city": -2140479,
    "guests": {
      "number_of_adults": 2,
      "number_of_rooms": 1
    }
  }'
```

These are also useful when looking at accommodation that have been recently modified in different countries using the [/accommodations/details/changes endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/details/changes).


```json
{
  "last_change": "2025-09-29T17:00:00+00:00",
  "filters": {
    "countries": [
      "nl",
      "es",
      "in"
    ]
  }
}
```

Note: Use lowercase for countries. See the [Code standards](/demand/docs/development-guide/code-conventions#country-codes) for correct formatting.

#### Handling cities with identical names

City names are not guaranteed to be unique. Multiple cities may share the same name across different regions or countries.

* The /locations/cities endpoint does not provide region-level disambiguation for cities with identical names.
* To identify the correct city, use the coordinates returned in the response together with the city name.


We recommend storing both the city ID and coordinates for the selected destination and using them in subsequent accommodation searches.

## Sorting

The `sort` object controls the order of results. You can specify the sorting field and direction.

| Parameter | Type | Description |
|  --- | --- | --- |
| `by` | string | Field to sort by. Options: `distance`, `price`, `review_score`, `stars`. |
| `direction` | string | Sort direction. Options: `ascending`, `descending`. |


### Sort results by distance

When sorting by distance make sure to specify the coordinates, including latitude, longitude and radius.


```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-25",
  "coordinates": {
    "latitude": 52.378281,
    "longitude": 4.900070,
    "radius": 100
  },
  "sort": {
    "by": "distance",
    "direction": "descending"
  },
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}
```

Use `distance` only if `coordinates` are provided.

### Sort results by review score and stars rating

Make sure you include the rating object with the review score and stars values.


```json
 "rating": {
    "minimum_review_score": 8,
    "stars": [4,5]
  },
```

### Sort results by prices

When sorting results by pricing, make sure you use "ascending" direction to return the most affordable results on top. Example:


```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-11-10",
  "checkout": "2026-11-25",
  "city": -2140479,
  "sort": {
    "by": "price",
    "direction": "ascending"
  },
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}
```

Note: The sorting direction is always "descending" by default.

## Key notes

* Price filtering requires a `currency` parameter.
* Sorting by distance requires coordinates (latitude, longitude, radius).
* You can combine filters and sorting to get highly tailored search results.
* Results are paginated using rows (max results per page) and page (pagination token).


Curious to know more?
- Refer to the [Search use cases section](/demand/docs/accommodations/search-examples) for more examples.
- See the [Search for accommodation guide](/demand/docs/accommodations/search-for-available-properties) for search best practices.
- Check the [Pagination guide](/demand/docs/development-guide/pagination) for details on using rows, and pagination token.
- Implementing v3.2? Check the [Accommodation search migration guide](/demand/docs/migration-guide/v3.2/accommodations/search) for details.