Hotel APIs Guide

Use the JSON Hotel APIs to search hotels; retrieve property details, availability and rates; and book a room/s. This guide discusses basic information about what each Hotel request does. Object-level details such as supported formats and values are covered in the Hotel API References.

Related Content: Hotel API References, Hotel Workflow Diagram

In this guide:

• Workflow Summary
• Hotel Search
• Hotel Details
• Hotel Availability
• Hotel Rules
• Create Hotel Reservation
• Modify or Cancel a Hotel Reservation

Workflow Summary

The minimum required hotel booking workflow is:

1. Search for hotel/s.

2. Request availability.

3. Send booking request.

The following optional steps can be added:

• Request additional details and images after the search.

• Retrieve the rules associated with a specific rate after the availability request.

Hotel Search

The Hotel Search API allows you to search for hotels either by location or by one or more property IDs:

• Search by location uses a GET request with query parameters to send either geographic coordinate information; the city, state or province, and country; or the IATA airport or city code.

• Search by property ID/s sends a POST request with a message payload specifying the property ID/s to send.

The response uses the same structure for both the GET and POST requests to return a list of properties based on the criteria sent.

After the search request, you must availability for a specific property per below before booking. If desired, you can send a Details request to retrieve a detailed description and images.

Pagination

Hotel Search uses pagination by default. The initial search response includes the total number of properties found under the search and the identifier to be used for retrieving additional pages. Call the GET pagination endpoint to retrieve each additional page of 25 properties until the end of the list is reached.

The identifier used for paging is saved for 30 minutes. A new hotel search request must be performed after it expires.

Hotel Details

After a hotel search, you can send the optional Hotel Details request to retrieve a detailed property description and images for one specific property.

Hotel Availability

Hotel Availability returns the room types and rates available at one or more specified properties on specified dates. Send Availability after the Search request. You can also send an optional Details request before Availability.

You can request availability for a single property with minimal rate modifiers, or for up to 10 properties. The request supports multiple rate categories and multiple rate plans, including the number of rate plans to return.

After availability, you can book a room with a Reservation request.

See the Hotel Availability API Reference for details on the following features.

Tax Breakdown Details

The Availability response returns structured tax and fee details specific to each hotel provider. Some hotel providers return only totals and others return full breakdowns. The following hotel providers send a full tax breakdown information:

• 1G Host Providers: Return total taxes but not total fee breakdown.

• Marriott chains: Return total taxes but not a breakdown.

• Hilton chains: Return total taxes but not a breakdown.

• Expedia properties: Return totals, taxes, fees, and breakdowns.

Grouping Common Property Details

Sending the optional indicator verboseResponseInd set to true disables the return of group common information about each property in ReferenceList. Instead, details for each property are returned in the individual Offer/Products/Product object.

Setting Maximum Response Time

The optional maxResponseWaitTime object allows you to set the length of time to wait for a response, after which time the request times out and returns all properties retrieved at that point.

Requesting Multiple Properties

You can request availability for up to 10 properties in a single request by sending an instance of PropertyRequest for each.

If specifying rate plan codes for each property, the request must include both the PropertyRequest and RateCandidatesDetail objects in HotelSearchCriterion . You must also associate each rateCode with a chain and property code for proper association.

Requesting Multiple Rate Plans

You can specify the number of rate plans to return in the response, up to 99. The actual number returned depends on how many rate plans the property has available and how many rates the property returns in one "scoop." A scoop is one request to the property. Each property/chain returns a different number of rates in a single scoop. The following example details how many rates an Availability response might return.

Scenario 1: You request 50 rate plans for a property. The property has 90 rate plans available for your search criteria, and it returns 30 rates plans per scoop; i.e., for every request Travelport makes to this property, it returns 30 rate plans.

After every response from the property, the API checks to determine if there are enough rates to send a response based on how many rates were requested, or if the property has run out of rates. On the first request, the property returns 30 rates and since this is less than the 50 requested, the API makes another request to the property to get back the next scoop. On the second request, the property sends back the next scoop of rates; i.e., the next 30. The total number of rate plans received so far is checked against the requested number and because it is more than what was requested, the response returns 60 rate plans to you. The API does not drop 10 rate plans to send the exact number of 50 requested.

Scenario 2: You request 50 rate plans for a property. The property has 40 rate plans available for your search criteria. The property also returns 30 rates plans per scoop; i.e., for every request that Travelport makes to this property, it returns 30 rate plans.

On the first request, the property returns 30 rates and since this is less than the 50 you requested, the API makes another request to the property to retrieve the next scoop. In this case, since the property has only 40 total rates available, it returns the last 10 rates. While this is less than the 50 requested, the property does not have any more rates to return, so the response returns 40 rate plans.

Requesting More Rates

If the request does not include the numberOfRatePlans parameter, by default, the Availability response returns the first scoop of rates as returned by the provider. The response indicates if additional rates are available and provides the moreRatesToken - a token to pass in with subsequent requests to retrieve those rates. You can then either request a specific number of rates using numberOfRatePlans, or you can send the token to retrieve as many rates as the provider sends. If you send the numberOfRatePlans parameter, you can expect to receive multiple scoops of rates from the provider, equal to or greater than the value of that parameter. If you do not send in the numberOfRatePlans parameter, you will get back only the first scoop of rates and a token to retrieve more rates, if available.

Hotel Rules

Hotel Rules is an optional request that retrieves the rules associated with a specific rate. It must be sent after an Availability response and returns rate rules, terms and conditions, and hotel policy information for a specific rate. This information is useful for conveying information such as extra charges and cancellation policies to your customers.

The rules returned are both informational and actual restrictions or requirements. Different properties can return a different range of rate rules, so the data returned can vary based on the chain and property.

Create Hotel Reservation

The Hotel Create Reservation API books a room. You can book by either:

• Sending full details: Send the booking code from the Availability response, check-in and check-out dates, rate details, and payment and traveler information.

• Sending a cached offer ID: Send the offer ID from the Availability response along with payment and traveler information. Sending the cached offer ID also returns more details in Price, Terms and Conditions, and Product.

After either request, the response returns a reservation locator (the reservation), a reservation confirmation, and a supplier locator, which is the confirmation number from the property. The supplier locator can be used to cancel the reservation later if needed. The response also includes the total price and any terms and conditions.

Agency IATA Number

Create Reservation supports sending an agency IATA number to include in the reservation when the booking is made, enabling that agency to receive their booking commission from the hotel. If an IATA number is not sent in the Create Reservation request payload, it is extracted from the PCC sent in the request header and included in the reservation.

Modify or Cancel a Hotel Reservation

After booking, you can modify or cancel a reservation as described below, or add another reservation to the booking.

Modify a Reservation

Hotel Modify allows you to modify an existing hotel reservation by changing some or all of the following:

• dates

• payment information

• traveler first and/or last name

Hotel Modify sends the reservation locator (reservation) of the reservation to modify, and the supplier locator (confirmation number from the supplier). Additional required objects depend on what you are changing:

• To change dates, send the DateRange object with the new dates for the booking.

• To modify payment information, send the FormOfPayment object. Do not include the DateRange object.

• To modify the traveler name, send Traveler/PersonName with the new given and/or surname.

• To add a comment to an existing reservation, send ReservationComment with the new comment.

You can modify any or all of these objects in the same request.

Add Reservation to reservation

Hotel Add Reservation allows you to add a hotel booking to an existing travel itinerary, or reservation. You must first send Search and Availability requests for the hotel booking you want to make, with an optional Details request between search and availability.

Cancel

Hotel Cancel allows you to cancel an existing hotel reservation. It requires the record locator and the confirmation number from the Reservation response.