Migrating from /hotelAvailability (version 2) to /accommodations/search (v3)

Overview

In version 2, the hotelAvailability endpoint returns the cheapest available room for each hotel that matches a traveller’s search criteria.

In version 3, the equivalent endpoint is /accommodations/search. This endpoint returns accommodations with at least one available product (or product combination) matching the search criteria for a traveller’s stay.

The search response returns:

The ID of every accommodation that has at least one available product (or product combination) that matches the search criteria.
The price of the product(s) that Booking.com recommends as the best match.
Results sorted by popularity (also known as Top picks) if the search is by country or region.
Optional sorting by other criteria (price, distance, etc.).

Important

Do not assume that parameters and fields work the same way in version 3 as in version 2.

V3 is a significant redesign of the Demand API, and many features work differently. Refer to this guide, the API reference, and your own testing to ensure a successful migration.

Request parameter mappings

Use the following tables to migrate request parameters from v2 to v3.

Location parameters

v2 query parameter	v3 equivalent
`airport`	`airport`
`city_ids`, `countries`, `district_ids`, `landmark_ids`, `region_ids`	`city`, `country`, `district`, `landmark`, `region`
`hotel\_ids`	`accommodations`
`latitude`, `longitude`, `radius`	coordinates - `latitude`, - `longitude`, - `radius`

To retrieve locations in v3, use the common/locations API collection.

Dates and guests

v2 query parameter	v3 equivalent
`checkin`	`checkin`
`checkout`	`checkout`
`guest\_country`	`booker.country`
`guest\_ip`	Not available - Use `booker.country` instead.
`no\_rooms, room1..room30`	`guests` v3 handles allocation of guests to rooms differently to V2. See Guest details and room allocation.

Filter criteria

v2 query parameter	v3 equivalent
filter=free_cancellation filter=non_refundable	`cancellation_type`
filter=no_prepayment filter=sustainable	Not available
hotel_facility_type_ids	`accommodation_facilities`
max_price, min_price	`price`
mealplan	`meal_plan`
min_review_score, stars	`rating`
options=no_cc_filter options=show_test	Not available
options=no_dorms	`dormitories`
options=is_24hr	`24_hour_reception`
property_type	`accommodation_types`
room_facility_type_ids	`room_facilities`
show_only_deals	Not available

Refer to the Filtering and sorting guide for examples and best practices.

Extra information

v2 query parameter	V3 equivalent
extras=block_payment_options	`extras.products`
extras=hotel_details extras=hotel_amenities extras=room_amenities extras=room_details extras=room_policies,	Not available Use /accommodations/details endpoint to return this information.
extras=payment_terms, extras=sustainability	Not available

General

v2 query parameter	v3 equivalent
add_filtered rate	Not available
affiliate_id	`X-Affiliate-Id`
currency	`currency`
language	Not available This parameter is not needed because /accommodations/search does not return any translatable data.
user_platform	`booker.platform`

Sorting and pagination

v2 query parameter	v3 equivalent
offset	`page`
rows	`rows`
order_by	`sort.by` - The v2 order_by values `popularity` and `ranking` are not available. - Now `popularity` is set by default when searching by `country` or `region`. (Not applicable to `city` or `district`.)
order_dir	`sort.direction` The version 2 `order_dir` values asc and desc are not available. Use ascending and descending instead.

Refer to the Pagination guide for examples and best practices.

Response field mappings

Accommodation-level fields

v2 field	v3 equivalent
`hotel_id`	`id`
`hotel_currency_code`	`currency`
`hotel_url`	`url`
`deep_link_url`	`deep_link_url`
`net_price`, `price`	`price` — See the Pricing guide.
Most other fields (e.g. `address`, `stars`, `review_score`, `hotel_name`, `hotel_photo`)	Not available. Use /accommodations/details endpoint instead.
`cheapest_filtered_rate`, `default_language`, `sustainability`, `review_score_word`, `direct_payment`	Not available

Product - room level fields

v2 field	v3 equivalent
`block_id`	`id`
`adults`, `children`	`number_of_adults`, `children`
`room_id`	`room`
`room_name`, `room_type_id`, `room_amenities`	Not available. Use /accommodations/details endpoint.
`cancellation_type`, `refundable`, `refundable_until`	`policies.cancellation`
`all_inclusive`, `breakfast_included`, `full_board`, `half_board`	`policies.meal_plan`
`payment_options.pay_at_property`, `payment_options.pay_online`	`policies.payment.timings`
`extra_charge`, `net_price`, `price`	`price` — See the Pricing guide.
Deal fields: `deal_tagging.deal_name`, `discount_percentage`, `public_price`	`deal` object (see Deals section)
`num_rooms_available_at_this_price`	Not available. Use `/accommodations/availability`.
Payment-related fields like `deposit_required`, `pay_later_collection_date`, `payment_terms.*`	Not available. See the Payments guide.
`platform`	Not available

Deals in version 2 and version 3

In version 2, deal-related information was available through the deal_tagging.deal_name, deal_tagging.discount_percentage, and deal_tagging.public_price fields within the Rooms response schema of the /hotelAvailability endpoint.

In version 3, deal information is included in the deal object returned in accommodations/search response. The deal object includes:

discount_percentage - The total discount percentage applied to the product's public_price.
public_price - The original price of the product before any discounts.
price.book - The discounted price (public_price minus the discount_percentage).
tags - These tags help categorise discounts and identify promotions.

Types of deals available in v3 include:

Logged_in_deals - Exclusive offers for users meeting specific criteria.
Deal of the day - Daily promotions with discounts on selected properties.
Last minute deals - Discounts for bookings made shortly before check-in.
Limited-time deals - Offers valid for a short, predefined period, such as Black Friday.

See the Discounts section for more details.