Search use cases

This section provides examples of various search requests and responses for common use cases. These will help you determine the fields you need for your own searches.

Search request examples

Basic search request

A very basic request that uses only the mandatory fields, could be:

A couple looking for an overnight stay in Amsterdam.

Obtain the id for Amsterdam from /common/locations/cities.
Use the returned city id (-2140479) as the destination in your search.
Specify dates and number of rooms and adults.

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

Searching for hotel near to landmark

A business traveller looking for an overnight stay in Amsterdam, who wants a hotel close to the Amsterdam Central Station.

For this case, use coordinates rather than city as the destination.

Call /common/locations/landmarks with Amsterdam's id (-2140479) to obtain the list of key landmarks in Amsterdam and coordinates.
Copy the latitude and longitude of Amsterdam Central Station.
Set the returned coordinates and radius to 1 km for the search.
Use /accommodations/constants to get the id for hotels (204).
Include the returned hotel id in accommodation_types field.
Sort the results by distance, to prioritise hotels closest to the station.

{
  "coordinates": {
    "latitude": 52.378281,
    "longitude": 4.90007,
    "radius": 1
  },
  "accommodation_types": [204],
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "currency": "EUR",
  "checkin": "2025-03-09",
  "checkout": "2025-03-10",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 1
  },
  "sort": {
    "by": "distance",
    "direction": "descending"
  }
}

Finding rooms for a family with specific age children

A family group is planning a holiday in Spain. They are looking for a week-long stay in mid-late August in a hotel.
The group needs 3 rooms for:
2 parents with 2 young children, aged 2 and 3.
A single parent with two teenage children, aged 13 and 15.
2 grandparents.

To meet these requirements, apply the following filters:

accommodation_types: to include only hotels (204)
Use guests.children to specify the age of each child in the group.
Use guests.allocation to specify the desired occupancy for each room.

{
  "country": "es",
  "accommodation_types": [204],
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "currency": "EUR",
  "checkin": "2025-08-08",
  "checkout": "2025-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]
}

Filtering by accommodation_facilities and rating by review score

A family group looking for a beach-front villa in Spain with an 8+ review score for mid-late August.
The group requires 2 rooms for:
2 parents with 2 young children, aged 2 and 3.
2 grandparents.
The parents want to play tennis.
The grandparents require air-conditioning and a shower in their room.

Filters to apply:

accommodation_facilities: to include only accommodations that list tennis court (9) and beach front (146) as available facilities.
accommodation_types: to include 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 for each requested room.

{
  "country": "es",
  "accommodation_facilities": [9, 146],
  "accommodation_types": [213]
  "booker": {
    "platform": "desktop",
    "country": "nl"
  },
  "currency": "EUR",
  "checkin": "2025-08-08",
  "checkout": "2025-08-16",
  "guests": {
    "allocation": [{
        "children": [2, 3],
        "number_of_adults": 2
      },
      {
        "number_of_adults": 2
      }
    ],
    "number_of_rooms": 2,
    "number_of_adults": 4,
    "children": [2, 3]
  },
  "rating": {
    "minimum_review_score": 8
  },
  "room_facilities": [4, 11]
}

Filtering by price

To limit accommodations to a specific price range:

{ 
"currency": "EUR",
"checkin_date": "2024-11-10",
"checkout_date": "2024-11-15",
"location": {
"city": "-2140479"
},
"price_filter": {
"min_price": 80,
"max_price": 100
},
"guests": {
"adults": 2
}

Retrieving only top picks accommodation

To return only top picks accommodations, you must use either country or region in the location field of the search request.

Example using region:

Run the common/locations/regions to see the full list of region ids for the desired country (in this case Spain).
Include the region id (725 for Andalusia) in your search request to get top picks for that region.

{
  "booker": {
    "country": "es",
    "platform": "desktop"
  },
  "checkin": "2024-10-24",
  "checkout": "2024-10-28",
  "region": 725,

  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}

genius-bulb Use pagination to load a subset of results in each request. This helps reduce load times and improves performance.

Search response examples

Basic response (without `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"
}

With `extra_charges`

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

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

Only with `products`

When products are returned without extra_charges, each result provides detailed information about each product, including:

Room type.
Allocation of adults and children (with their ages).
Cancellation, meal, and payment policies.
Any deals applied.
Price 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"
}

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

With both `products` and `extra_charges`

When products and extra_charges the response provides a detailed breakdown of every charge applied to each product. The breakdown includes the charge type id, 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"
}

Reference

Refer to Prices in accommodation section for more details about extra-charges and price breakdown.