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
• API Versions 11 and 12
• Hotel Ratings in Hotel Search and Details Responses
• Using the Search by Location or by ID APIs (v11)
  • Request Structure
  • Response Structure
• Using the SearchComplete API (v12)
  • Request Structure
  • Response Structure

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.

Hotel Ratings in Search and Details Responses

The responses for Search by Location or ID, SearchComplete, and Hotel Details return hotel ratings from any of four sources depending on availability and content source:

• GIATA

• Booking.com (for Booking.com content)

• NorthStar

• AAA (American Automobile Association)

The Rating object for any offer provides any available ratings information for that property as available. Rating/provider returns the abbreviation for the provider supplying the score returned in Rating/value, which is an aggregated score based on the provider's criteria per the additional information in the dropdown menus below.

"Rating": [
     {
       "value": 4,
       "provider": "NTM"
     },
   {
      "value": 4,
      "provider": "AAA"
   }
            ],

Using the Search by Location or ID APIs (v11)

The JSON Hotel APIs currently offer two APIs for searching: Search by Location and Search by ID. They return search results in the same format. You must send the number of guests and either a location to search or specific property IDs to search. After either search, you can optionally retrieve additional property-level information with the Hotel Details request, and you must send an Availability before booking to confirm availability on the room/s you want to book.

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 property 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

Using the SearchComplete API (v12)

The SearchComplete API combines the search, details, and availability functionality available in the v11 APIs as three separate requests. In addition to sending the number of guests and location, you can narrow the search results returned by several rate-, room-, and property-specific criteria as detailed below.

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:

• negotiated rates: Send the rate code/s for any private rates for your company or organization

• rate categories A rate specific to a characteristic or organization, such as government, military, senior, corporate, etc. such as military, government, senior, etc.

• to return all available Image URLs (which in v11 are returned only via a separate Details request), send returnAllImageURLs with true; sending false returns a smaller set of images

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 property 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 type A standard category of room, such as a double room, king room, or suite. at that property. Each roomTypes instance returns:

  • characteristics, bed types, and maximum occupancy for that room

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

  • room amenities

  • an array of rates objects. Each instance is one unique rate plan The package of price, terms, and amenities for a specific hotel room. Each room type may have multiple rate plans depending on payment terms, refundability, and inclusions such as breakfast, parking, or wifi. for that room type at that property. Each rates instance returns:

    • room and rate descriptions

    • rate code details including the rateCode, ratePlanID, rateCategory, rateCategoryCode, and whether the rate is public or private

    • quantity of the rooms at that property at this rate

    • indicators for whether breakfast, lunch, and dinner are included

    • price and terms for this rate plan