Last updated

Search for available properties


Use the /accommodations/search endpoint to search for accommodation that has at least one available product that matches the search criteria for a traveller's stay.

The request defines the search criteria to be used.

The response returns:

  • the id of every accommodation that has at least one available product (or product combination) that matches the search criteria.
  • for each accommodation, the price of the product(s) that Booking.com recommends as the best match for the search criteria.

Create the search request body

Travellers' search requirements can vary enormously, from the simple and precise to the vague and complex.

The /accommodations/search request schema provides an extensive range of input options. This allows you to construct search requests that can:

  • cover the whole spectrum of travellers' requirements as efficiently as possible.
  • find and return the optimum set of matching results for the traveller, so that they can find their ideal accommodation easily and quickly. This in turn maximises the chances of them converting the search to a booking.

Mandatory fields

The request body must contain the following fields:

  • One (and only one) destination field.
  • The basic details about the guest(s):
    • checkin and checkout: their arrival and departure dates
    • guests.number_of_adults: the number of adults who will be staying
    • guests.number_of_rooms: the number of rooms they need
  • The basic details about the booker:
    • booker.platform: the platform from which the request is being made. This ensures that any platform-based prices and deals can be returned correctly.
    • booker.country: the country from which the request is being made. This is required to ensure that the response complies with relevant laws on the display of taxes and fees.

See Example 1. All other fields are optional.

Destination fields

You must specify one (and only one) of the following fields to define the geographic target of the search request:

  • country, region, city, district, airport or landmark - The id of a single geographic location. You can get these ids by using the /common/locations endpoints.

  • coordinates - An object defining the latitude and longitude of the centre of the search, and the radius (in km) from that point defining the limit of the search.

    You can get the coordinates of a landmark by using /common/locations/landmarks, or of an accommodation by using /accommodations/details. You can also use coordinates sourced in any other way.

  • accommodations - A list of accommodation ids. This could be a list built from the response to a previous search request, or a list created for a specific purpose. For example, a promotion on your search page for a specific set of hotels near a particular beach.

See Example 2.

Guest Details and room allocation

If any children will be staying, define the age of each child in the guests.children field. For example, [3,3,8,12]specifies four children, two aged 3, one aged 8 and one aged 12.

If you want specific combinations of guests to share individual rooms, use the guests.allocation field.

  1. Create an array of objects under guests.allocation, one object for each room.
  2. In each object:
    • In children, add the age of each child who should occupy the room. Omit the field if no children are staying in this room.
    • In number_of_adults, add the number of adults who should occupy the room. Each room must contain at least one adult.

Make sure that:

  • The total number of objects matches the number specified in guests.number_of_rooms.
  • The total number of children allocated to rooms, and their ages, matches the information specified in guests.children.
  • The total number of adults allocated to rooms matches the number specified in guests.number_of_adults.

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]
}

Filter criteria

The following tables summarise the available filters, some of which work on the accommodation level, and some on the product level.

For specific information about each filter, see the request schema.

Accommodation-level filters

FieldDescription
24_hour_receptionOnly return accommodation that has 24-hour reception cover.
accommodation_facilitiesOnly return accommodation that has a specific set of facilities. For example, a restaurant, sea view and tennis court.
accommodation_typesOnly return specific types of accommodation. For example, only return hotels, apartments and boats.
brandsOnly return accommodation that belongs to a particular corporate brand.
dormitoriesInclude or exclude dormitory accommodation.
rating.minimum_review_scoreOnly return accommodation that has a review score of at least n
rating.starsOnly return accommodation that has a specific number of stars.
travel_proudOnly return accommodation that is a member of the Booking.com Travel Proud programme.

Product-level filters

FieldDescription
room_facilitiesOnly return products with rooms that have a specific set of facilities. For example, air conditioning and a balcony.
paymentInclude or exclude products that require use of a credit card.
priceOnly return products in a specific price range.
cancellation_typeOnly return products that have a specific cancellation policy.
meal_planOnly return products that offer specific meal plans. For example, breakfast included or half-board.

Extra information

By default, the response contains only basic information about matching accommodation and price. You can use the extras field to return additional information about extra_charges and products, as shown in the following examples.

Example 1: Basic response (no extras requested)

Each result in the list includes the following information:

  • The accommodation's unique identifier (id).
  • the total price and currency of the product(s) that Booking.com recommends as the best match for the search criteria,
  • the url (and deep_link_url for mobile apps)
{
  "id": 3882311,
  "currency": "GBP",
  "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2023-05-10&checkout=2023-05-12&mcid=10",
  "price": {
    "book": 180.34,
    "total": 180.34
  },
  "url": "https://www.booking.com/hotel/nl/demand-api-test-1.html?aid=956509&checkin=2023-05-10&checkout=2023-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10"
}

Example 2: With extra_charges

When extra_charges are returned (without products), each result also includes a summary breakdown of the charges applied to the price of the recommended product (or product combination).

See the schema description of the price object for more details.

{
  "id": 3882311,
  "currency": "GBP",
  "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2023-05-10&checkout=2023-05-12&mcid=10",
  "price": {
    "base": 176.81,
    "book": 180.34,
    "extra_charges": {
      "excluded": 0.00,
      "included": 3.54
    },
    "total": 180.34
  },
  "url": "https://www.booking.com/hotel/nl/demand-api-test-1.html?aid=956509&checkin=2023-05-10&checkout=2023-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10"
}

Example 3: With products

When products are returned (without extra_charges), each result also includes the following information about each included product:

  • the type of room that is included
  • the number of adults and children (shown by their ages) allocated to the room
  • the applicable cancellation, meal and payment policies
  • any deals that are applied
  • the price

Refer to the schema description of the products.policies object for more details.

{
  "id": 3882311,
  "currency": "GBP",
  "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2023-05-10&checkout=2023-05-12&mcid=10",
  "price": {
    "book": 180.34,
    "total": 180.34
  },
  "products": [{
    "id": "388231102_367857842_0_2_0",
    "children": [],
    "deal": null,
    "number_of_adults": 2,
    "policies": {
      "cancellation": {
        "free_cancellation_until": "2023-05-02T21:59:59+00:00",
        "type": "free_cancellation"
      },
      "meal_plan": {
        "meals": [],
        "plan": "no_plan"
      },
      "payment": {
        "types": [
          "pay_now",
          "pay_later"
        ]
      }
    },
    "price": {
      "book": 180.34,
      "total": 180.34
    },
    "room": 388231102
  }],
  "url": "https://www.booking.com/hotel/nl/demand-api-test-1.html?aid=956509&checkin=2023-05-10&checkout=2023-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10"
}

Example 4: With both products and extra_charges

When products and extra_charges are returned, each result also includes a complete breakdown of every charge that has been applied to each product. The breakdown shows the id of the charge type, how it is applied, and how it is calculated.

See the schema description of the products.price object for more details.

{
  "id": 3882311,
  "currency": "GBP",
  "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2023-05-10&checkout=2023-05-12&mcid=10",
  "price": {
    "base": 176.81,
    "book": 180.34,
    "extra_charges": {
      "excluded": 0.00,
      "included": 3.54
    },
    "total": 180.34
  },
  "products": [{
    "id": "388231102_367857842_0_2_0",
    "children": [],
    "deal": null,
    "number_of_adults": 2,
    "policies": {
      "cancellation": {
        "free_cancellation_until": "2023-05-02T21:59:59+00:00",
        "type": "free_cancellation"
      },
      "meal_plan": {
        "meals": [],
        "plan": "no_plan"
      },
      "payment": {
        "types": [
          "pay_now",
          "pay_later"
        ]
      }
    },
    "price": {
      "base": 176.81,
      "book": 180.34,
      "extra_charges": {
        "conditional": [],
        "excluded": [],
        "included": [{
          "charge": 1,
          "mode": "per_person_per_night",
          "percentage": null,
          "total_amount": 3.54,
          "unit_amount": 0.88
        }]
      },
      "total": 180.34
    },
    "room": 388231102
  }],
  "url": "https://www.booking.com/hotel/nl/demand-api-test-1.html?aid=956509&checkin=2023-05-10&checkout=2023-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10"
}

Search request examples

Example 1

A couple looking for an overnight stay in Amsterdam. This is a very basic request that uses only the mandatory fields.

Use city as the destination. You can obtain the id for Amsterdam from /common/locations/cities.

{
  "city": -2140479,
  "booker": {
    "platform": "desktop",
    "country": "gb"
  },
  "checkin": "2023-03-09",
  "checkout": "2023-03-10",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}

Example 2

A business traveller looking for an overnight stay in Amsterdam, who wants a hotel within a short walk of the Amsterdam Central Station.

  1. Use coordinates rather than city as the destination. To obtain the latitude and longitude of the Amsterdam Central Station, call /common/locations/landmarks, using Amsterdam's id (-2140479) as an input.
  2. Define the radius for the search as 1 km.
  3. Add a filter for accommodation_types to include only hotels (204). You can get this id from /accommodations/constants.
  4. Sort the results by distance, so that hotels closest to the station are highest in the list.
{
  "coordinates": {
    "latitude": 52.378281,
    "longitude": 4.900070,
    "radius": 1
  },
  "accommodation_types": [204],
  "booker": {
    "platform": "desktop",
    "country": "gb"
  },
  "currency": "GBP",
  "checkin": "2023-03-09",
  "checkout": "2023-03-10",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 1
  },
  "sort": {
    "by": "distance",
    "direction": "descending"
  }
}

Example 3

A family group are in the early stages of planning a holiday somewhere in Spain, with a beachfront location. They are looking for a week or so in mid-late August in a hotel, resort or villa, with an 8+ review score. They will need 3 rooms, for:

  • 2 parents with 2 young children, aged 2, 3.
  • A single parent with two teenage children, aged 13 and 15
  • 2 grandparents

The parents want to play tennis. The grandparents want a room with air-conditioning and a shower.

To meet these requirements in the search:

  • Use filters for:

    • accommodation_facilities, to include only accommodations that list tennis court (9) and beach front (146) as available facilities.

    • accommodation_types, to include only hotels (204), resorts (206) and villas (213).

    • rating.minimum_review_score, to include only accommodations with an 8+ review score.

    • room_facilities, to include only products that include rooms with air-conditioning (11) and a shower (4).

      You can obtain the necessary ids by calling /accommodations/constants.

  • Use guests.children to specify the age of each child in the group.

  • Use guests.allocation to specify the desired occupancy - adults and children - for each requested room.

Also, because the recommended product(s) will include multiple rooms, use the extras field to include details of the product(s) in the response.

{
  "country": "es",
  "accommodation_facilities": [9, 146],
  "accommodation_types": [204, 206, 213],
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "currency": "EUR",
  "checkin": "2023-08-08",
  "checkout": "2023-08-16",
  "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]
  },
  "rating": {
    "minimum_review_score": 8
  },
  "room_facilities": [4, 11]
}