Skip to main content

Developer Migration Guide

Introduction

Like you, we use a lot of APIs as we develop our software. Once we learn about a new set of APIs, test against them, integrate with them, and deploy our working application, all feels right in the world. What happens when APIs change? Well, we need to start the process again: learn, test, integrate, and deploy.

We have found by experience that understanding an API change is easier when a good migration guide exists. Migration guides are a specific type of technical documentation to assist developers in changing their source code when adapting to an API upgrade.

Using the guide

Reading a good API reference tells a developer how to set up a request to an API and what to expect back in response. That type of information was published with the release of the Content Services for Lodging APIs.

After carefully watching, listening, and learning from our customers approaching the new lodging APIs for their system architecture, we knew we needed to provide a guide to help with the migration from our legacy Hotel service.

With the help of this guide, you should see information clearly telling you why the change has occurred, and how to easily reason about the new design. Furthermore, you should see what the specific mappings of APIs and data models are.

Seeing capabilities

Looking at the migration guide one will notice some telling differences between the legacy hotel services and the new lodging APIs.

Aggregators

Inventory across all sources have been combined with what the GDS provides to create a new data structure. As you look through the API responses notice the formal ways all the dynamic data has been flattened and mapped together. Individual property prices can be easily compared to one another.

Greater use of RESTful APIs

REST is a well-known architectural pattern that may be familiar to your development team. If so, consider using the RESTful lodging APIs because they are feature-complete compared to the SOAP editions. If you do switch to using RESTful, you will encounter the CreatePNR API to book properties.

Granular and orchestrated APIs

Decide if using granular or orchestrated versions of the lodging APIs is best for your application’s workflow. If your user experience benefits from richer data provided by orchestration – use those APIs. If you have a need for concise, granular APIs, they are ready for integration too. Some teams will choose to mix-and-match.

Unique identifiers

Several ways of referring to the collection of data structures across the portfolio of APIs exists. Look for these in API responses: Hotel Code, Rate Key, and Booking Key. They all play an important role at various points of your application workflow.

Property search – multiple properties

Request

Legacy hotel API

The HotelAvailability OTA_HotelAvailLLSRQ API has typically been used as the first step in the shopping process. It enables shopping across a broad set of properties using a basic airport code, city code, or city name search, with the optional addition of other search criteria.

Content Services for Lodging

The GetHotelAvailRQ API, available in SOAP and REST, provides multiple location resolution methods (or a specific property search) for a specific stay period and occupancy. It has multiple advanced search filter options based on property/image content and enables customization of the availability response.

Differences

The major differences between the two services include:

  • Ability to request aggregator content alongside Sabre GDS chains, based on access
  • A live shopped rate is returned in the response from each supply source requested in the search, where available. This includes up to 40 GDS properties with a rate, and up to 200 from an aggregator.
  • Hotel Amenity code searching has switched to use Open Travel Alliance codes
  • A unique Rate key is used to identify individual products with the shopping response
  • Multiple rooms can be searched with aggregators, along with child and child ages
  • Rate Type and searching using Client IDs
  • Using Sabre Hotel Code or Global Property Code
  • A numeric Hotel Brand Code will eventually replace the Sabre Chain Code
  • Sabre Property Rating is a Sabre derived rating (from 0 to 5, including .5 values), designating the relative quality of the property in the response.  It is based on a Sabre proprietary algorithm from multiple sources.
  • Rate Assured is no longer supported within the shopping response

Response

Legacy Hotel API

The HotelAvailability OTA_HotelAvailLLSRS API response provides a list of hotel options with a rate range and availability indicator, across a broad set of properties, using a basic airport code, city code, or city name search, with the optional addition of other search criteria. Additional fields include amenity and other availability indicators.

Content Services for Lodging

GetHotelAvail, available in SOAP and REST, returns up to 200 properties per page, sorted on client-selectable criteria. This includes Rate, Distance, Rating, and Agency Retailing (if the Agency subscribes with basic property information). The service also returns a lead image (hero) per property. A lead rate (one per property) or multiple lead rates (per property from different supply sources) can be accessed based on the request. A shop key is used to paginate through the results to manage large responses.

Differences

The major differences between the two services include:

  • Removal of some legacy values from the response that provide low/no value, or low supplier participation:

    AreaID, GEO_ConfidenceLevel, DC_AvailParticipant, DC_SellParticipant, LocationDescription, CityList, Alt_Avail, RatesExceedMax, SpecialOffers

  • A unique RateKey replaces the line number in the response, which can be used to validate pricing further into the workflow.

Product search - single property

Request

Legacy Hotel API

The HotelPropertyDescription HotelPropertyDescriptionLLSRQ API provides details on available room rates by room and rate type for a single property.

Content Services for Lodging

The GetHotelDetails API, available in SOAP and REST, provides information on the availability of specific properties, together with all the descriptive and visual content, from all requested supply sources based on a stay period and occupancy. This API requests specific Rate Plan Codes, Rate Plan Types and Client IDs, Loyalty and Corporate Discount IDs, and pre-paid/post-paid rates across all supply sources, or per supply source. Specific static property descriptive and image content can be submitted in the request.

Important! Due to the stateless nature of CSL, if Get Hotel Avail has been used in a prior workflow request, the property ID (Global ID or Sabre ID) must be used in the request to Get Hotel Details. LineNumber used in the HotelPropertyDescription API cannot be used.

Differences

Additional features available in GetHotelDetails that are not included in HotelPropertyDescription include:

  • Multiple room search
  • Rate search from different supply sources (including chains and rates from specific aggregators)
  • Specification of number of children and child ages

The addition of rate qualifiers enables more specific responses that include pre-paid/post paid rates based on cancellation policy/refundability and currency conversion.

Property-descriptive content in the response includes:

  • ShortDescription
  • Alerts
  • Dining
  • Facilities
  • Recreation
  • Services
  • Attractions
  • Property level cancellation policy
  • Deposit policy
  • Directions
  • Policies
  • Safety information
  • Transportation information
  • AdditionalCharges
  • PointOfInterests
  • Airports
  • AcceptedCreditCards
  • GuaranteePolicies

Image content can be requested by selecting filters for image type, captions, and more. Refer to the Reference section on the API's page for all current image filters.

Response

Legacy Hotel API

Responses are based on real time requests to hotel suppliers with actual rates and rooms available at the time of request. The API allows the user to provide rate codes and qualifiers to shop for the applicable rates, and robust property descriptive content is provided with each rate.

Content Services for Lodging

The GetHotelDetails API, available in SOAP and REST, returns the pricing summary and breakdown, payment indicators, cancellation and guarantee policies, and commission information from the supply sources that have been searched. It provides a highly structured response, including grouping options of the product (rooms/rate plans) that are available at the specific property based on search criteria used. Descriptive content for the selected property is retrieved from an index. Media (image/video) for the property is converted into the requested format and returned in the response. Availability requests are sent out to all selected rate sources, and all the available products are returned in the response. The purpose of the GetHotelDetails API is to orchestrate all this information in its response for a single property.

Differences

The GetHotelDetails response is significantly more structured than its nearest equivalent service – HotelPropertyDescription. It returns TierLabels for revenue optimization, product breakdowns, including with and without taxes and fees, and provides more details about each room and rate in specific fields where available.

Note: Additional features are still underway that will provide full details of each room/rate inclusions, including bed and room type, board basis (meal plan), value adds/inclusions, commission and guest loyalty, and other important information.

  • The GeoConfidence indicator is not included in the GetHotelDetails response.

  • DirectConnect content, including DC_Avail and DC_Sell Participant, RequestFail, and Unavail indicators have been removed from the response as they are redundant.

  • IndexData, including points of interest relative to the specific property, are not included in the GetHotelDetail response.

  • Property options in the HotelPropertyDescription response (for property level amenities) have been replaced with the available Property Amenities included at the requested property, including the OTA amenity code, based on the request.

  • Media content is returned based on filters used in the request.

Rate selection – single property, single product/rate

Request

Legacy Hotel API

The HotelRateDescription API provides all applicable rules, policies, and restrictions governing the use of a requested hotel rate. The request includes the shopping criteria for the specific product that the rules, policies, and restrictions are applicable to.

Content Services for Lodging

The HotelPriceCheck API, available in SOAP and REST, serves as the step between Shopping and Booking methods. This API ensures the price returned while shopping for a chosen product is still applicable, and is the lowest possible, just prior to booking. The input for the API is the RateKey returned from GetHotelAvail, GetHotelDetails, or the granular APIs, GetHotelLeadRate/GetHotelRateInfo.

Differences

A significant number of details are available in the Get Hotel Details or Get Hotel Rate Details API regarding the product selection, much of which did not previously return in the HotelPropertyDescriptionLLSRQ API.

While Hotel Price Check is a mandatory API in order to provide a BookingKey, it's also used to validate that a previously shopped product/rate is still available from the requested supply source at the shopped price.

To simplify the API, the only input parameter for Hotel Price Check is an encrypted RateKey which uniquely identifies the product/rate for that particular shop.

Response

Legacy Hotel API

The HotelRateDescription response includes details of the property, with the requested rate/product included in the request. These details provide the applicable rules, policies, and restrictions governing the use of the specific hotel rate.

Content Services for Lodging

The Hotel Price Check response details the latest information for the chosen product along with any observed changes in rates. This includes:

  • HotelRateInfo - Returns rate-specific information for the property.
  • BookingKey - A uniquely generated key needed to make a hotel reservation.
  • PriceChange indicator - If true, the price has changed in the supplier's returned currency.
  • PriceDifference - Returns the amount by which the rate was increased or decreased in the supplier's returned currency.
  • CurrencyCode - Returns the supplier's returned IATA (ISO 4217) currency code.
  • ConvertedPriceChange - If true, the price has changed in the user's requested currency.
  • ConvertedPriceDifference - Returns the amount by which the rate was increased or decreased in the user's requested currency.
  • ConvertedCurrencyCode - Returns the user's requested IATA (ISO 417) currency code.
  • RateInfos - A collection of information about rates for a request from all suppliers.
  • Rooms - Describes the information of a hotel room for a property.

On receipt of the request to Hotel Price Check, a valid RateKey is then decrypted by Sabre and a re-shop takes place.

Differences

If the room/rate from the supply source is the same as from the original rate key, a successful response is returned. Provided in the response is a BookingKey, a new encrypted field which can be used across the CSL Booking APIs – EnhancedHotelBook, UpdateRes or Create PNR.

If the room/rate from the supply source is not the same as what was originally provided in the shopping APIs, a message is shown, and a new shop must be carried out. If a successful product match has been made, any differences in the price are shown in the response.

Booking of rate

Request

Legacy Hotel API

The Book Hotel Reservation OTA_HotelResLLSRQ API is used to a) reserve one or more hotel rooms and b) create a hotel segment in a passenger name record (PNR).

This API allows client applications to sell a hotel reservation from a hotel description.

Note: A PNR containing at least a name and an address must be in the current session/Sabre work area.

To reserve a room from a hotel description, the client application must obtain the pertinent line number from the Hotel Property Description API response message.

Content Services for Lodging

To book a rate that was shopped through CSL, API clients have a couple of options depending on the workflow implemented.

In order to book a rate, the BookingKey provided in a successful response from Hotel Price Check is required. In addition, other information required to make the booking includes:

  • The PNR locator (if adding the lodging segment to a previously made booking)
  • Guest details
  • Special requests
  • Form of payment
  • Agency details

Differences

The introduction of the BookingKey as the identifier is the most significant change to available CSL booking services.

All bookings made using CSL APIs will create an active segment in the Sabre PNR. This includes aggregator content.

Depending on which booking option was used and which method of booking, the segment type can vary.

In EnhancedHotelBook, for GDS bookings, bookgdsaslegacy is available, which creates the hotel booking and formats the segment using the same rules as the existing functionality provided in the OTA HotelRes API.

EnhancedHotelBook can also be used to book GDS content as a CSL HHL segment, along with the aggregator.

Special requests and loyalty IDs can also be added in the request.

Agency name and address information is required in the PNR request.

Response

Legacy Hotel API

The BookHotelReservation OTA_HotelResLLSRQ API response provides the details of a successful booking, which includes the PNR locator and the confirmation number from the booking supply source.

Content Services for Lodging

Upon a successful booking, the PNR locator and the confirmation number from the booking supply source are returned.

Note: The response received will vary depending on the booking option, but the key elements mentioned above will always be included.

Retrieve a previously made booking

Request

Legacy Hotel API

The GetReservationRQ API by retrieves and displays a passenger name record (PNR), along with data related to the PNR.

The request payload can be further specified by using ReturnOptions, which determines the response message content. There are three types of requests available:

  • Stateless: Full data is provided at creation, and the ET and Locator are provided at the end of the request.
  • Stateful: Data is provided at creation, no ET and no Locator is provided at the end of the request.
  • Trip: No ET is provided and no Locator is provided.
Which request type should I use?
  • Accesses: For Read Only Access, use the Trip option, as the PNR is not unpacked into the user's AAA session. The PNR Locator must always be specified in the request. For Update Access, use the Stateful option, as this unpacks the PNR into the user's AAA session and is available for any follow-up Sabre entries.
  • Locators: If a Locator is specified in the request, the service checks the Locator in the AAA session.
    • If they match, the API retrieves current data in the AAA session.
    • If they do not match, the API unpacks the PNR into the AAA session (if the current session is available and there are no outstanding updates).

Content Services for Lodging

A new schema version for the request of the SOAP v1.19 API was introduced with the following main items:

  • Includes new capabilities for hotel content
  • Enables authorized users to mark PNRs as suspicious
  • Includes informational segment flags
  • Introduces a new indicator to identify OA flights that are third party booked
  • Create hotel bookings in a stateless way, regardless of the content source:
    • Agency private rates from suppliers through direct connect
    • Hotel aggregators
    • Traditional hoteliers through the GDS path
  • Enables customers to connect to different sources of content. Provide rates from different suppliers for the same hotel and allow the customer to choose which one to book.

Important! There are no major changes to support CSL APIs in the new version of GetReservationRQ.

Response

Legacy Hotel API

The response will retrieve the requested PNR based on the criteria used in the request.

Content Services for Lodging

The response will retrieve the requested PNR based on the criteria used in the request and includes support for bookings made using CSL APIs.

Differences

The Lodging segment includes a number of new fields, including:

  • BookingKey
  • Confirmation number from the supply source (including aggregators)
  • Support for Global Property IDs and identification of the InfoSource, which designates the supply source the room/rate was booked through.

All bookings made using CSL APIs are handled as active segments in Sabre (HK).