Migration Guide

## Timing and Support for v1 - New features will only be added to v2 of the API. - Major bugfixes and support will continue for v1 until July 2, 2018. After this date, v1 will no longer be supported. Bugs will no longer be fixed, and users who request support for v1 will be directed to upgrade to v2 in order to obtain support. - Users may migrate one endpoint at a time and use a combination of v1 and v2 endpoints as they transition. ## ## What's New In v2? - v2 is faster, more stable, and much simpler to use. - Our static content endpoints have been revamped to make getting content easier, faster, and more intuitive. Content such as photos and descriptions are now delivered by a single **/hotels** call which provides the requested content. - The method by which **/changedHotels** monitors and delivers changed content has been improved. It now specifies in detail what has been changed, not only the hotel_id. - All endpoint names and parameters have been standardised across the entire API. - Enabling new versions of the API allows many improvements to be launched at the same time and allows partners to test new functionalities before migrating. - The API usage guides on [developers.booking.com](https://developers.booking.com/api/index.html?version=2.4) have been revised and updated. For more details on these and other improvements, see below. ## ## Multiple Endpoints - Strict output typing has been implemented: - Strict typing of JSON (booleans, integers, floats, strings) - Strict typing of XML-RPC (all types XML-RPC supports) - Specifying JSON is no longer required in URL paths and JSON will be provided by default. - Boolean output is now 'true' or 'false' instead of 1 or 0. - All image URLs will be HTTPS only. - Parameter errors will return HTTP status code 400. This includes unknown parameters and parameters with empty values. - XML-RPC calls must have the correct 'Content/Type=text/xml'. - The way endpoints support multiple translations has changed. Instead of one item per translation, there is now a 'translations' nested field containing the translations (if available). - Note: some parameters and endpoints are restricted based on partner permissions. For example, **/processBooking** requires a special contract and a partner SSL certificate. ## ## Policies The **/getPolicies** endpoint has been removed. Default policies will be returned from the **/hotels** endpoint. Other policies can be retrieved from **/blockAvailability**. ## Static Content: **/hotels** Endpoint The following endpoints have all been replaced with the v2 **/hotels** endpoint: - GetHotels - GetHotelTranslations - GetHotelDescriptionTranslations - GetHotelDescriptionPhotos - GetHotelFacilities - GetHotelPhotos - GetCreditcards - GetPolicies - GetRooms - GetRoomTranslations - GetRoomFacilities - GetRoomPhotos - GetDistrictHotels - GetRegionHotels - GetChains - GetHotelLogoPhotos Please see the [technical documentation](https://www.google.com/url?q=https://developers.booking.com/api/technical.html&sa=D&ust=1555069528858000&usg=AFQjCNHIJdQkZ_qzkpN9DzK8m2kAqOEWtw) for more details on how to use the **/hotels** endpoint. ## Changes to Specific Endpoints **Note:** Only more complex changes are listed here. For renamed parameters and other changes, see the mapping table at the bottom of this page. **/blockAvailability** - HTML has been removed from the policies output. - The fields for meal plans, extra charges, and title (POLICY_TITLE) were removed from the policies output. - In v2, meal plan information can be generated by passing extras=mealplan - In v2, extra charges can be generated by passing extras=extra_charges - room_desc field from block_text was moved to block object and renamed room_description. - block_text content was moved to block object. - hotel_text content was moved to hotel object. - The split_block_text parameter was removed. - The cancellation policy that was shown in block object now can be found in the block policies list. - For more examples, see the [technical documentation](https://www.google.com/url?q=https://developers.booking.com/api/technical.html&sa=D&ust=1555069528858000&usg=AFQjCNHIJdQkZ_qzkpN9DzK8m2kAqOEWtw). ## ## /changedHotels - Output is now more granular based on the specific hotel information that has changed. - See the [technical documentation](https://www.google.com/url?q=https://developers.booking.com/api/technical.html&sa=D&ust=1555069528858000&usg=AFQjCNHIJdQkZ_qzkpN9DzK8m2kAqOEWtw) for examples and more information. ## ## /bookingDetails - The status field has been changed. - Previous values: S, F, C, and NS. - New values: stayed, booked, cancelled, and no_show. ## ## /processBooking Booker address must be included for properties that require it. The **/hotels** endpoint contains this information. ## /getHotelAvailability (Legacy Version) - In v1 of the API, there were two distinct availability endpoints with similar names: - /getHotelAvailability (v1) - /getHotelAvailabilityV2 - The older v1 endpoint has been retired and is not included in v2 of the API. - The endpoint **/getHotelAvailabilityV2** has been renamed **/hotelAvailability** in v2 of the API. - For details about other changes, see the mapping table below. ## ## Mapping Table See the [mapping table](https://bstatic.com/backend_static/common/dist/affiliate_api/V2 endpoint input param and output field changes.pdf) for a comprehensive overview of endpoint changes between v1 and v2.