Search for accommodation v3.2

Learn how to use the /accommodations/search endpoint to retrieve accommodations that match your travellers' search criteria.

→ Use the /accommodations/search endpoint to retrieve accommodations with availability matching the search criteria.

• By default, the response returns the most affordable available product for each accommodation.
• When searching by country or region, results are ranked by Booking.com popularity ("Top picks") rather than price, unless you specify a different sorting method.

The request defines criteria such as:

• Travel dates.
• Booker information.
• Number of guests and rooms.
• Location or specific accommodations.
• Optional filters and sorting.

The response can include, for each accommodation:

• The accommodation ID.
• Price and currency information.
• Commission information.
• The cheapest available product and its policies.
• Additional product and charge information when requested.
• URLs for web and deep-link access.

The /accommodations/search request requires:

• booker
• checkin
• checkout
• guests

You can use optional fields to define the search area, restrict the results, request additional information, filter or sort accommodations, and control pagination.

Example search request

{
  "booker": {
    "country": "gb",
    "platform": "desktop"
  },
  "checkin": "2026-08-15",
  "checkout": "2026-08-25",
  "city": -2612321,
  "extras": [
    "extra_charges",
    "products"
  ],
  "guests": {
    "number_of_adults": 4,
    "number_of_rooms": 2
  }
}

Include the booker object in every search request.

For example:

{
  "booker": {
    "country": "gb",
    "platform": "desktop"
  }
}

The booker information identifies relevant characteristics of the traveller and the platform from which the request originates.

• booker.country - Country of the booker.
• booker.platform - Platform from which the search is made.

Use the values supported by the booker schema for the API version you are using.

Provide the traveller's arrival and departure dates:

• checkin - Check-in date.
• checkout - Check-out date.

Both fields are mandatory.

For example:

{
  "checkin": "2026-08-15",
  "checkout": "2026-08-25"
}

Use the date format defined by the API reference.

You can use location or accommodation criteria to limit the search results.

The endpoint supports:

• airport
• city
• coordinates
• country
• district
• landmark
• region
• accommodations

Use the corresponding /common/locations endpoints to retrieve location IDs where required.

For example, to search within a city:

{
  "city": -2612321
}

You can similarly search using an airport, country, district, landmark, or region identifier.

Use coordinates to restrict results to an area around a geographical point.

The object supports:

• latitude - Latitude of the centre of the search area.
• longitude - Longitude of the centre of the search area.
• radius - Search radius around the specified latitude and longitude, in kilometres.

For example:

{
  "coordinates": {
    "latitude": 52.378281,
    "longitude": 4.900070,
    "radius": 1
  }
}

You can obtain coordinates for a landmark using the relevant /common/locations endpoint or for an accommodation using /accommodations/details.

Use accommodations to restrict the search to specific accommodation IDs.

You can provide up to 100 accommodation IDs.

For example:

{
  "accommodations": [
    10004,
    10005,
    10006
  ]
}

This can be useful when searching availability and prices for a predefined set of accommodations.

Use guests to define the travellers and number of rooms required.

At minimum, specify the guest information required by the guests schema for the API version you are using.

For example:

{
  "guests": {
    "number_of_adults": 4,
    "number_of_rooms": 2
  }
}

You can also provide children and room allocation information when required.

For example:

{
  "guests": {
    "allocation": [
      {
        "children": [13, 15],
        "number_of_adults": 1
      },
      {
        "children": [2, 3],
        "number_of_adults": 2
      },
      {
        "number_of_adults": 2
      }
    ],
    "number_of_rooms": 3,
    "number_of_adults": 5,
    "children": [2, 3, 13, 15]
  }
}

When using guest allocation:

• Create one allocation object for each room.
• Specify the number of adults allocated to each room.
• Include the ages of children allocated to each room when applicable.
• Ensure the overall guest information and room allocation are consistent.

Use optional request fields to request additional response data, filter results, specify currency, control pagination, and define sorting.

Use extras to request additional information in the response.

The supported values are:

• extra_charges
• products

For example:

{
  "extras": [
    "extra_charges",
    "products"
  ]
}

extras enriches the response; it does not filter the search results.

Use products when you need product-level information such as room allocation, policies, inventory, and product-level prices.

Use currency when you need prices in a specific supported currency.

For example:

{
  "currency": "EUR"
}

You must specify currency when using filters.price.

Use filters to restrict search results according to accommodation or product characteristics.

In version 3.2, you can filter by criteria including:

• Accommodation and room facilities.
• Accommodation types and brands.
• Cancellation type and meal plan.
• Payment requirements.
• Price per night.
• Review score and star rating.
• Sustainability certification and Travel Proud certification.
• 24-hour reception.
• Dormitory inclusion or exclusion.

For example:

{
  "currency": "EUR",
  "filters": {
    "price": {
      "minimum": 100,
      "maximum": 250
    },
    "rating": {
      "minimum_review_score": 8,
      "stars": [4, 5]
    }
  }
}

Use sort to control the order in which accommodations are returned.

You can sort results by:

• distance
• price
• review_score
• stars

Use sort.direction to specify ascending or descending order.

Use rows to specify the maximum number of results to return according to the limits defined by the API.

Use page with the pagination token returned in metadata.next_page to retrieve the next page of results.

The response returns matching accommodations in the data array.

By default, the endpoint returns the cheapest available product for each accommodation.

Each accommodation can include:

• id - Accommodation ID.
• commission - Commission information.
• currency - Accommodation and booker currencies.
• deep_link_url - Affiliate deep link.
• price - Accommodation-level price information.
• products - Product-level information when requested using extras.
• url - Booking.com web page URL.

The accommodation-level price object provides the applicable price information for the search result.

In version 3.2, this includes structures for:

• Base price.
• Charges.
• Display price.
• Total price.

Price amounts can be returned in accommodation and booker currencies.

For complete pricing behaviour and the meaning of the different price structures, see the Accommodation pricing guide.

To retrieve product-level information, include products in extras:

{
  "extras": [
    "products"
  ]
}

Each returned product can contain:

• id - Product ID.
• bundle - Bundle identifier, when applicable.
• children - Ages of the children allocated to the product.
• deal - Deal information, when applicable.
• inventory - Inventory information for the product.
• number_available - Number of rooms available at the returned price.
• number_of_adults - Number of adults allocated to the product.
• policies - Product policies, including cancellation, meal plan, and payment information.
• price - Product-level price information.
• room - Room ID.

The inventory object provides inventory-related information, including whether the product comes from third-party inventory.

When you search using country or region, results are ranked by Booking.com popularity ("Top picks") rather than price by default, with higher-ranked accommodations appearing first.

To order the results using another supported criterion, provide sort.by.

For example:

{
  "country": "nl",
  "sort": {
    "by": "review_score",
    "direction": "descending"
  }
}

See the Filtering and sorting guide for more information.

When more search results are available, the response returns a pagination token in metadata.next_page.

For example:

{
  "metadata": {
    "next_page": "token_abc123"
  }
}

Pass the returned token using page in the next request to retrieve the next page of results.

The following simplified example shows the main response structure:

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 10004,
      "currency": {
        "accommodation": "EUR",
        "booker": "EUR"
      },
      "deep_link_url": "booking://hotel/10004?...",
      "price": {
        "base": {
          "accommodation_currency": 1081.49,
          "booker_currency": 1081.49
        },
        "display": {
          "accommodation_currency": 1260.52,
          "booker_currency": 1260.52
        },
        "total": {
          "accommodation_currency": 1260.52,
          "booker_currency": 1260.52
        }
      },
      "products": [
        {
          "id": "1000420_95127794_2_0_0",
          "bundle": null,
          "children": [],
          "deal": null,
          "inventory": {
            "third_party": false,
            "type": "sell"
          },
          "number_of_adults": 2,
          "policies": {
            "cancellation": {
              "free_cancellation_until": null,
              "type": "non_refundable"
            },
            "meal_plan": {
              "meals": [],
              "plan": "no_plan"
            },
            "payment": {
              "timings": [
                "pay_at_the_property"
              ]
            }
          },
          "room": "1000425"
        }
      ],
      "url": "https://www.booking.com/hotel/nl/..."
    }
  ],
  "metadata": {
    "next_page": "token_abc123"
  }
}

A valid search can return an empty data array when no accommodations or products match the search criteria.

If no results are returned, review criteria such as:

• Travel dates.
• Location.
• Guest configuration.
• Accommodation IDs.
• Filters.
• Price range.

You can also check current accommodation information using the relevant accommodation details endpoints where appropriate.

Not all Booking.com accommodation inventory or prices are necessarily available through the Demand API.

As a result, the accommodations, products, or prices returned by the Demand API can differ from those displayed on the Booking.com website or app.