# Filtering and sorting accommodation results v3.2

**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](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/search) returns the cheapest available product for each accommodation matching your search criteria.

Top picks ranking
When applying location criteria such as `country` or `region`, results are ranked by Booking.com popularity (top picks), with higher-ranked accommodations appearing 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

Filters are specified under the `filters` object in the request body. The table below lists all parameters supported inside the `filters` object in v3.2.

Other search criteria, such as `city`, `country`, `region`, `airport`, `landmark`, `coordinates`, and `accommodations`, are specified as top-level fields in the request body.

| Filter | Description |
|  --- | --- |
| `24_hour_reception` | Only include accommodations with 24/7 front desk reception. Set `true` to filter accordingly. |
| `accommodation_facilities` | Filter by property facilities (e.g., Parking, Restaurant).* Use IDs from [accommodations/constants](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/constants).

 |
| `accommodation_types` | Filter by property type (e.g., Apartment, Hotel, Hostel).* Use IDs from [accommodations/constants](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/constants).

 |
| `brands` | Filter by brand (e.g., Radisson Blu, Westin).* Use IDs from [/accommodations/chains](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/chains).

 |
| `cancellation_type` | Filter by cancellation type. Options: `free_cancellation` (`non_refundable` is deprecated). |
| `dormitories` | Include or exclude dormitory rooms/beds. Options: `include` (default), `exclude`, `only`. |
| `meal_plan` | Filter by meal plan. Options: `all_inclusive`, `breakfast_included`, `full_board`, `half_board`. |
| `payment` | Payment filters:* `credit_card_required` (boolean) – only show accommodations requiring credit cards.
* `timing` (string) – filter by payment timing: `pay_at_the_property`, `pay_online`.

 |
| `price` | Filter by price per night. Requires the `currency` parameter.* `minimum` (number) – minimum price per night. Omit to indicate no lower limit.
* `maximum` (number) – maximum price per night. Omit to indicate no upper limit.
* Specify at least one of `minimum` or `maximum`.

 |
| `rating` | Filter by property rating:* `minimum_review_score` (1–10)
* `stars` (array of integers, 1–5)

 |
| `room_facilities` | Filter by room facilities (e.g., TV, Air Conditioning).* Use IDs from [accommodations/constants](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/constants).

 |
| `sustainability_certification` | Filter for properties with sustainability certification.* Set `true` to include only certified accommodations.

 |
| `travel_proud` | Filter for LGBTQ+ friendly properties (Proud Certified).* Set `true` to include only Proud Certified accommodations.

 |


Filters can be combined. Only accommodations matching all criteria will be returned.

## Sorting

Use the `sort` object to control the order in which results are returned.

Specify the field to sort by using `by` and the sort direction using `direction`.

| Parameter | Description |
|  --- | --- |
| `by`
 | Field to sort by:
* `distance`
* `price`
* `review_score`
* `stars`

When sorting by `distance`, you must provide `coordinates` in the request. Distance sorting supports ascending order only.
 |
| `direction`
 | Sort direction:
* `ascending`
* `descending`

Descending order is not supported when sorting by `distance`.
 |


Example of sorting accommodations by price in ascending order:

```json
"sort": {
  "by": "price",
  "direction": "ascending"
}
```

This returns the lowest-priced accommodations first.

## Practical filtering examples

### Search by facilities and rating

Use `accommodation_facilities` to filter based on facilities available at the accommodation, and `room_facilities` to filter based on facilities available in rooms.

Some accommodation facilities include:

| Facility  | Description |
|  --- | --- |
| `Wi-Fi` | Search for properties that offer free or paid Wi-Fi. |
| `Parking` | Filter for accommodations with available parking facilities. |
| `Pool` | Search for accommodations that have swimming pools. |
| `Air conditioning` | Filter based on whether air conditioning is available. |
| `Pet-Friendly` | Locate properties that allow pets. |
| `Kitchen facilities` | Find accommodations with kitchen or kitchenette facilities. |
| `Fitness center` | Search for accommodations with on-site fitness facilities. |
| `Accessibility` | Search for accommodations with facilities that cater to guests with disabilities. |


→ Get facility IDs from [accommodations/constants](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/constants).

Example of a search request filtering by:

* Accommodation facilities: parking (`2`) and restaurant (`3`).
* Room facilities: air conditioning (`11`).
* Minimum review score: `8`.
* Star rating: `4` or `5` stars.


```json
"filters": {
  "accommodation_facilities": [2, 3],
  "room_facilities": [11],
  "rating": {
    "minimum_review_score": 8,
    "stars": [4, 5]
  }
}
```

This request returns accommodations matching the specified accommodation and room facilities, with a minimum review score of 8 and a 4- or 5-star rating.

### 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/3.2/demand-api/accommodations/accommodations/search), [accommodations/availability](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/availability) and [accommodations/details](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/details) requests.

Example of search request for pay at the property timing:

```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-property.

Example in accommodations/details request:

```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

Use the `price` filter to restrict results based on the price per night.

The `price` filter requires at least one price boundary. Specify `minimum`, `maximum`, or both. If you don't want to filter results by price, omit the `price` filter from the request.

| Filter: | Description |
|  --- | --- |
| `minimum` | Sets the minimum price per night, in the specified currency. Results below this price are excluded. Omit `minimum` to apply no lower price limit. |
| `maximum` | Sets the maximum price per night, in the specified currency. Results above this price are excluded. Omit `maximum` to apply no upper price limit. |


When both `minimum` and `maximum` are specified, only results where the price per night falls within the specified range, inclusive, are returned.

For example, the following request searches for accommodations in Amsterdam costing between 100 EUR and 200 EUR per night:

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

#### Important when filtering by price

* Always include `currency` when using the price filter.
* When including the `price` filter, you must specify at least one of `minimum` or `maximum`. You can specify both to define a price range.
* Do not send an empty `price` object (`"price": {}`).
  * If no minimum or maximum price is required, omit the `price` filter from the request.
  * An empty `price` object returns an invalid parameter error.


### Search by sustainability and LGBTQ+ friendly properties

```json
"filters": {
  "sustainability_certification": true,
  "travel_proud": true
}
```

* This request returns only accommodations that are both Proud Certified and sustainability-certified.


### Search by accommodation brand

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

→ Use the [accommodations/chains](/demand/docs/open-api/3.2/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.

* 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
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-05-09",
  "checkout": "2026-05-12",
  "city": -2140479,
  "extras": ["extra_charges", "products"],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "filters": {
    "brands": [19]
  }
}
```

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

### Search for 24h reception accommodation

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

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

### Search by distance

You can restrict your search based on distance.

#### 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/3.2/demand-api/commonlocations/common/locations/landmarks) for landmarks.
* [/accommodations/details](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/details) for an accommodation.
* [/locations/country](/demand/docs/open-api/3.2/demand-api/commonlocations/common/locations/countries) for countries.


Example:

* This query filters 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": "2025-03-09",
  "checkout": "2025-03-10",
  "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](/demand/docs/open-api/3.2/demand-api/commonlocations/common/locations/landmarks) to get the list of landmarks (and their ids) in a selected city.


Example for Paris (-1456928):

Request:

```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": "2025-10-10",
  "checkout": "2025-10-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 restrict accommodation search results using geographic criteria. Location criteria are specified as top-level fields in the request body rather than inside the `filters` object.

| Field | Description | Get IDs using |
|  --- | --- | --- |
| `city` | Restrict results to a specific city. | [locations/cities](/demand/docs/open-api/3.2/demand-api/commonlocations/common/locations/cities) |
| `country` | Restrict results to a specific country. | [locations/countries](/demand/docs/open-api/3.2/demand-api/commonlocations/common/locations/countries) |
| `region` | Restrict results to a specific region within a country. | [locations/regions](/demand/docs/open-api/3.2/demand-api/commonlocations/common/locations/regions) |
| `airport` | Restrict results using a specific airport. | [locations/airports](/demand/docs/open-api/3.2/demand-api/commonlocations/common/locations/airports) |
| `landmark` | Restrict results using a specific landmark. | [locations/landmarks](/demand/docs/open-api/3.2/demand-api/commonlocations/common/locations/landmarks) |


You can also use `coordinates` to search within a specified radius of a latitude and longitude.

→ Retrieve location IDs from [common/locations](/demand/docs/open-api/3.2/demand-api/commonlocations).

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](/demand/docs/open-api/3.2/demand-api/commonlocations/common/locations/cities) 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.

## Key notes

* Parameters inside the `filters` object can be combined to narrow down accommodation results.
* Location criteria such as `city`, `country`, `region`, `airport`, `landmark`, and `coordinates` are specified as top-level request fields, not inside `filters`.
* Price filtering requires the `currency` parameter and at least one of `minimum` or `maximum`.
* Do not send an empty `price` object (`"price": {}`). Omit the `price` filter when no price restriction is required.
* Sorting by `distance` requires `coordinates` and supports ascending order only.
* You can combine filters and sorting to tailor search results.
* Results are paginated using `rows` (maximum results per page) and `page` (pagination token). See the [Pagination guide](/demand/docs/development-guide/pagination).


* Refer to the [Search use cases section](/demand/docs/accommodations/search-examples) for more examples.
* See the [Search for accommodation](/demand/docs/accommodations/search-for-available-properties) guide for more information on setting up search requests.