Hotel Search Guide

The first step in every workflow - creating a reservation or adding segments to an existing reservation - is to search for a hotel room. This guide compares the three APIs Travelport offers for searching, and details the structure of the request and response for each.

Object-level details such as supported formats and values are covered in the corresponding API references for each API.

In this guide:

Basic Concepts

In addition to the Basic Concepts in the JSON Hotel APIs Guide, which include many travel industry terms, the following terms are useful when searching for hotels:

  • IATA code: IATA is the International Air Transportation Association, an organization that standardizes rules, regulations and fare construction principles for the international travel industry. IATA creates standardized codes used across air, hotel, rail, etc. to identify locations (cities and airports) and specific brands, amenities, characteristics, and so on.

  • Guest count: All search requests require a guest count to determine accurate pricing and availability. Guests include all travelers on a booking, including adults, children, and infants.

API Versions 11 and 12

The JSON Hotel APIs provide three APIs for searching hotels, which is the first step in any workflow:

  • Search by Location: Search for hotels by a geographic location: address, coordinates, or a city or airport code.

  • Search by ID: Search for hotels by property ID.

Both of the above APIs are on model version 11 (see the discussion in the following section). You can use either request depending on the search criteria you would like to use. Either request must be followed by an Availability request before you can book a room. Optionally, you can also send a Details request to return additional hotel details such as property images.

  • SearchComplete API: Currently in development, SearchComplete combines into a single API the information that in v11 is returned in separate search, details, and availability requests. SearchComplete is based on ODM v12. Functionality on v12 is available only for SearchComplete at this time, so after your SearchComplete request, you can proceed straight to booking with the v11 Create Reservation API. Or, you can request Rules before booking if desired. No additional step is required before booking after a SearchComplete request.

JSON Hotel SearchComplete is not yet available as a general release. All details in this documentation are for informational purposes only and subject to change until General Availability release, which will be communicated in advance via a Travelport Developer Advisory.

Search by Location or ID v11

The JSON Hotel APIs currently offer two APIs for searching: Search by Location and Search by ID.

Request Structure

The following diagram illustrates the high-level structure of the two v11 search APIs. Requests include several objects; only the top-level objects are shown. Required objects are marked with a red asterisk* both in the diagram and in the following explanatory text.

In both APIs, every request requires CheckInDate* and CheckOutDate* to set the dates of the stay.

RoomStayCandidate* is required to send the number of travelers for the booking. If children are on the booking, specify counts and ages here.

For Search by Location, the SearchBy* object is required to send the location to search, which can be the city IATA, airport IATA code, a location such as a city, state/province, and country, or by property ID. You can also set a radius around the search location to search, or accept the defaults.

Search by ID sends PropertyKey* instead of SearchBy. PropertyKey is an array that sends up to 250 specific property and chain code IDs to limit the search results to only those specific properties.

Response Structure

The following diagram illustrates the high-level structure of all search v11 responses. The format is the same whether Search by Location or Search by ID was sent. Responses include many objects; only the most relevant are shown. Depending on search criteria, supplier-provided details, or other factors, not all of the following may be returned in every response for every property. Arrays are shown in red text both in the diagram and in the following explanatory text.

The beginning of the response returns an Identifier, a tracking ID in the traceId object (see Trace and Transaction IDs), and pagination details for this response (see JSON Hotel APIs Guide). Depending on search criteria and availability, the search can return up to 100 properties. If more rooms are available, totalProperties notes the total number available, and you can retrieve those results with the Search Pagination API.

The bulk of the response is in the PropertyInfo object. Each instance is one unique propertyClosed The hotel itself.. Each PropertyInfo instance returns:

  • the property's id, name, and property key (chain and property codes)

  • in propertyInfo, property-level details such as id, availability, and distance from search location

  • a Property object that returns

    • property location and ratings,

    • a single featured property image URLs (additional images can be retrieved separately with a Hotel Details request)

    • property address and contact details

    • an array of amenities

  • the lowest available rate at the property for the stay

  • the highest available rate at the property for the stay

SearchComplete (v12 )

Request Structure

The following diagram illustrates the high-level structure of SearchComplete v12 requests. Requests can include many objects; only the top-level objects are shown. Required objects are marked with a red asterisk* both in the diagram and in the following explanatory text.

Every request requires stayDetails* that include the check-in and check-out dates, and the number of travelers for the booking. Optionally, you can send the number of rooms you want to book, or leave it blank to stay with the default of 1.

The propertyFilter* object is required to send the location to search, which can be the city code, airport code, a location such as a city, state/province, and country, or by property ID. You can also set a radius around the search location to search, or accept the defaults. propertyFilter also requires the number of travelers for the booking. If children are on the booking, specify counts and ages here.

Remaining propertyFilter search criteria are optional. You can narrow the results search by any or all of the following:

  • a string of characters in the hotel name

  • specific chains by code

  • return only available properties

The following property criteria don't narrow the search but do provide more options:

The optional roomFilter object narrows results to only room types that meet criteria such as non smoking, balcony, accessible, connecting, by bed configuration (for example, a minimum of two king beds), and/or specific amenity codes.

The optional rateFilter object narrows results by criteria for the types of rates to return, such as refundable, breakfast or other meals included, deposit or prepayment required, and commission.

 

Response Structure

The following diagram illustrates the high-level structure of SearchComplete v12 responses. Responses include many objects; only the most relevant are shown. Depending on search criteria, supplier-provided details, or other factors, not all of the following may be returned in every response for every property. Arrays are shown in red text both in the diagram and in the following explanatory text.

The beginning of the response returns tracking IDs in the traceId and transactionId objects (see Trace and Transaction IDs), and pagination details for this response (see JSON Hotel APIs Guide). Depending on search criteria and availability, SearchComplete can return up to 100 properties in its response. If more rooms are available, pagination/totalItems notes the total number available, and you can retrieve those results with the SearchComplete Pagination API.

The bulk of the response is in the hotelsResponse object. The hotelsResponse object first returns data that applies to the entire search, including the check-in and -out dates for the stay in the local time of the search location.

After these high-level details, SearchComplete returns an array of propertyItems objects. Each instance is one unique propertyClosed The hotel itself.. Each propertyItems instance returns:

  • the property's name, and the brand, chain, and property codes

  • in propertyInfo, property-level details such as

    • property location and ratings,

    • property image URLs (in v11 images are retrieved separately with a Hotel Details request)

    • a Boolean indicator for availability (unless the search requested only available properties; in v11 availability is retrieved separately with a required Availability request).

  • Up to four individual pricing objects that each return the same objects and information for either filtered or unfiltered public rates or, for searches with a rate code, private rates:

    • the total price, base, and taxes for the entire stay

    • the average nightly price, base, and taxes

    • rate code details for the property

    • a rateKey value that must be sent in any subsequent Create Reservation reference payload request

  • An array of roomTypes objects. Each instance is one unique room typeClosed A standard category of room, such as a double room, king room, or suite. at that property. Each roomTypes instance returns: