Attention: Please check the Hotel Release Notes page for the latest updates and enhancements.

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.

Workflow Summary

The minimum required hotel booking workflow is:

Search for hotel/s.
Request availability.
Send booking request.

The following optional steps can be added:

Request additional details and images for a property after the search.
Retrieve the rules associated with a specific rate after the availability request.

Hotel Standard Search

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

Standard search by location to search by either geographic coordinate information, or the city, state/province, and country, or the IATA airport or city code.
Standard search by property ID/s to search by one or more property IDs.

The standard search qualifiers include: Dates, Chain Codes, Brand Codes, Negotiated Rate Codes, Distance.

The response returns a list of properties based on either the property list or location sent.

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

Hotel Precision Search

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

Precision search by location to search by either geographic coordinate information, or the city, state/province, and country, or the IATA airport or city code.
Precision search by property ID/s to search by one or more property IDs.

The standard search qualifiers include: Dates, Chain Codes, Brand Codes, Negotiated Rate Codes, Distance, Rate Category, Prepay Rates, Postpay Rates, Commissionable Rates, Refundable Rates, Non-smoking rates, Room Amenities.

The response returns a list of properties based on either the property list or location sent.

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

Rights to Precision Search and Precision Availability must be granted by Travelport. Please contact your Travelport representative if interested.

Hotel Search Pagination

Hotel Search uses pagination by default. The initial search response returns 25 properties and an identifier to be used for retrieving additional pages, and notes the total number of properties found. Use the GET search pagination request to retrieve each additional page of 25 properties until the end of the list is reached.

The identifier used for pagination 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 Standard Availability

Hotel Standard Availability returns the room types and rates available at one or more specified properties on specified dates. You can send a Standard Availability request either directly after a Standard Search request, or you can send an optional Details request to retrieve a detailed property description and images.

You can request standard availability for a single property with minimal rate modifiers, or for up to 10 properties. The request supports multiple rate categories. The response returns a maximum of 100 rates per property per page until all rates are received.

In the v11 release, each rate returned in the response has a unique offer ID value. You can use this offer ID as a reference identifier when either requesting rules for or booking that offer, using a reference payload request for your Rules or Create Reservation request per below.

Hotel Standard Availability supports the following options; see the Hotel Standard Availability API Reference for details:

Consolidating common offer details: By default, Availability consolidates common information across offers into the ReferenceList object. This can reduce response time by not repeating information in multiple offers. To disable this feature, send the verboseResponseInd indicator set to true to return all details with each offer.
Maximum response time: Optionally, you can set a timeout value in maxResponseWaitTime to set a length of time to wait for a response. After this time the request times out and returns all properties retrieved at that point

The Availability response returns structured tax and fee details. The tax details returned are specific to each hotel provider. Some hotel providers return only totals and others return full breakdowns. The hotel providers that send the new tax breakdown information are as follows:

1G Host Providers: Return Total Taxes, but do not return Total Fee breakdown.
Marriott chains: Return Total Taxes, but do not return a breakdown.
Hilton chains: Return Total Taxes, but do not return a breakdown.
Expedia properties: Return Totals, Taxes, Fees, and breakdowns.
Booking.com properties: Return Totals, Taxes, Fees, and breakdowns.

Hotel Precision Availability

Hotel Precision Availability returns the room types and rates available at one or more specified properties on specified dates using the qualifiers from the associated Hotel Precision Search. You can send a Precision Availability request either directly after a Precision Search request, or you can send an optional Details request to retrieve a detailed property description and images.

You can request availability for a single property or for up to 10 properties. The response returns a maximum of 100 rates per property per page until all rates are received.

Each rate returned in the response has a unique offer ID value. You can use this offer ID as a reference identifier when either requesting rules for or booking that offer, using a reference payload request for your Rules or Create Reservation request per below.

1G Host Providers: Return Total Taxes, but do not return Total Fee breakdown.
Marriott chains: Return Total Taxes, but do not return a breakdown.
Hilton chains: Return Total Taxes, but do not return a breakdown.
Expedia properties: Return Totals, Taxes, Fees, and breakdowns.
Booking.com properties: Return Totals, Taxes, Fees, and breakdowns.

Hotel Availability Pagination

Hotel Standard and Precision Availability use pagination by default. The initial availability response returns a maximum of 100 rates per property and an identifier to be used for retrieving additional pages, and notes the total number of rates found. Use the POST availability pagination request to retrieve each additional page of rates per property until the end of the list is reached.

The identifier used for availability pagination is saved for 30 minutes. A new hotel search and/or availability request must be performed after it expires.

Hotel Rules

Hotel Rules is an optional request that retrieves the rules associated with a specific rate. It can be sent after an Availability response to return 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.

Rules supports the following request formats:

Full payload request: Request the rules for a rate by sending full offer details including the check-in and check-out dates, rate details, and the booking code from the Availability response.
Reference payload request: Request the rules for a rate by sending a cached offer ID from the Hotel Availability response.

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. Create Reservation supports both of the following request formats:

Full payload request: Send full offer details including the check-in and check-out dates, rate details, and the booking code from the Availability response, along with traveler, form of payment, and payment information.
Reference payload request: Send a cached offer ID from the Hotel Availability response, along with traveler, form of payment, and payment information. Sending the cached offer ID also returns more details in Price, Terms and Conditions, and Product.

Offers in an Availability response are cached for 15 minutes. If a reservation with the offer ID is not created within 15 minutes, you must send a new Availability request before sending a reference payload request.

For either request, the response returns a reservation locator (the PNR), 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.

Modify, Add, 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
add comments to a reservation

Check the Reservation Modify page to see which systems support specific field modifications.

Hotel Modify sends the reservation locator (PNR) 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.
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.

When changing dates for a Travelport-booked hotel segment, it is recommended that you first send an availability request for the new dates and look for the same booking code that is on the existing reservation. An availability request is not mandatory, but a modify request will fail if the new dates are not available.

Add Reservation to PNR

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

Add Reservation supports both of the following request formats:

Full payload request: Send full offer details including the check-in and check-out dates, rate details, and the booking code from the Availability response, along with receipt, form of payment, and payment information.
Reference payload request: Send a cached offer ID from the Hotel Availability response, along with receipt, form of payment, and payment information.

Cancel

Hotel Cancel cancels an existing hotel reservation. It requires the record locator and the confirmation number from the Reservation response.

Hotel Retrieve

Hotel Retrieve returns the passenger and hotel reservation information for a requested PNR. It requires the record locator from the Reservation response.