/hotelAvailability - V3 migration guide

Endpoints

In V2, the hotelAvailability endpoint returns the cheapest available room for each hotel matching a traveller's check-in and check-out dates.

In V3, the equivalent endpoint is /accommodations/search. Use this endpoint to search for accommodations that has at least one available product that matches 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.
For each accommodation, the price of the product(s) that Booking.com recommends as the best match for the search criteria.
In case the search criteria in the request is for accommodations located in a specific country or region, the retrieved results are sorted by default based on "popularity" (also known as "Top picks").
However, you can still optionally use other "Sort.by" options, to get results based on price, distance, etc, instead.

Attention

Do not assume that mapped parameters or fields work in exactly the same way in V3 as they did in V2.

V3 is a significant redesign of the Demand API and some things work very differently. Use this documentation, the API Reference, and your own experimentation and testing to make sure that you migrate each V2 call correctly.

Request parameter mappings

Use the following tables to identify how to migrate request query parameters and response fields from a V2 call to the appropriate V3 equivalent.

Location

V2 query parameter	Equivalent V3 field
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	Equivalent V3 field
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	Equivalent V3 field
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 pagination section for examples and best practices.

Extra information

V2 query parameter	Equivalent V3 field
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 to return this information.
extras=payment_terms, extras=sustainability	Not available

General

V2 query parameter	Equivalent V3 field
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	Equivalent V3 field
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 V2 order_dir values asc and desc are not available. Use ascending and descending instead.

Refer to the pagination section for examples and best practices.

Response schema mappings

Result

V2 field	Equivalent V3 field
address, checkin_time, cc_required, cvc_required, country, hotel_amenities, hotel_name, hotel_photo, location, postcode, review_nr, review_score, stars	Not available Use /accommodations/details to obtain this information.
cheapest_filtered_rate, default_language, sustainability	Not available
deep_link_url	deep_link_url
direct_payment	Not available V3 handles payments differently to V2. Refer to the Payments guide for more details.
hotel_currency_code	currency
hotel_id	id
hotel_url	url
net_price,price	price: V3 handles prices differently to V2. See the Pricing guide for details and examples.
review_score_word	Not available Use /accommodations/constants to obtain this information.

Rooms -> products

V2 field	Equivalent V3 field
adults	`number\_of\_adults`
all_inclusive, breakfast_included, full_board, half_board	`policies.meal\_plan`
breakfast_cost	Not available
block_id	`id`
cancellation_type, refundable, refundable_until	`policies.cancellation`
children	`children`
deal_tagging.deal_name, deal_tagging.discount_percentage, deal_tagging.public_price	`deal`
platform	Not available
deposit_required	Not available
extra_charge, net_price, price	`price` V3 handles prices differently to V2. See the Pricing guide for details and examples.
num_rooms_available_at_this_price	Not available. Use /accommodations/availability to obtain this information.
pay_later_collection_date, payment_terms.cancellation_description, payment_terms.name, payment_terms.prepayment_description	Not available V3 handles payments differently to V2.
payment_options.pay_at_property, payment_options.pay_online	`policies.payment.timings`
room_amenities, room_name, room_type_id	Not available. Use /accommodations/details to obtain this information.
room_id	`room`
room_policies.class, room_policies.content, room_policies.mealplan_vector	Not available