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)
- Using the SearchComplete API (v12)
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" } ],
The following information is provided by GIATA about its hotel ratings:
GIATA is a Berlin-based travel technology company specializing in hotel content management, mapping, and distribution solutions for the tourism industry. At GIATA, Hotels are evaluated based on 239+ criteria across several categories:
-
Reception & Services: 24/7 front desk, multilingual staff, luggage service
-
Rooms: Size, furnishings, amenities like Wi-Fi, minibar, air conditioning
-
Food & Beverage: On-site restaurant, breakfast options, room service
-
Leisure & Events: Gym, spa, conference rooms
-
Cleanliness & Quality: Maintenance, hygiene, guest comfort
-
Online Presence: Website quality, booking options, digital services
Each star level has minimum requirements, and hotels can earn a “Superior” label if they exceed expectations for that category.
What Do the Stars Mean?
-
1 Star: Basic accommodation, clean rooms, limited services
-
2 Stars: Private bathrooms, better furnishings, breakfast service
-
3 Stars: 24/7 reception, restaurant, air conditioning
-
4 Stars: Concierge, gym/spa, multilingual staff, minibar
-
5 Stars: Luxury experience - gourmet dining, spacious rooms, personalized service, 24-hour room service
The following information is provided by Booking.com about its hotel ratings:
Booking.com 's traditional hotel star ratings (1 to 5 stars) is based on information provided by the hotel or certified by local tourism authorities. These ratings reflect the level of service, amenities, and comfort a guest can expect.
-
1 Star: Basic accommodation with minimal services.
-
2 Stars: Modest comfort, often with private bathrooms and basic amenities.
-
3 Stars: Mid-range hotels with reception services, dining options, and more room features.
-
4 Stars: High-quality service, larger rooms, and additional facilities like gyms or concierge.
-
5 Stars: Luxury experience with premium services, spacious rooms, and top-tier amenities.
Important Notes:
-
These ratings are not assigned by Booking.com.
-
They may vary slightly by country depending on local standards.
-
They help travelers quickly compare hotels based on expected quality.
The following information is provided by NorthStar about its hotel ratings:
NorthStar uses a 10-level system ranging from basic budget accommodations to ultra-luxury
-
Moderate Tourist Class – Basic, no-frills budget accommodations.
-
Tourist Class – Budget-friendly with minimal services; may be near highways or airports.
-
Superior Tourist Class – Mid-market economy hotels with functional amenities.
-
Moderate First Class – Comfortable, simple accommodations with modern essentials.
-
Limited Service First Class – Quality accommodations with limited public areas and dining.
-
First Class – Full-service hotel with amenities suitable for all travelers.
-
Superior First Class – Upscale with stylish design and broad services.
-
Moderate Deluxe – High-end, often business-focused hotels.
-
Deluxe – Exceptional luxury with upscale amenities and service.
-
Superior Deluxe – Top-tier, exclusive luxury hotels with personalized service.
The following information is provided by AAA about its hotel ratings:
AAA uses a 5-Diamond scale to indicate the level of service, amenities, and overall experience:
1 Diamond – Budget-oriented; basic accommodations with minimal services.
2 Diamonds – Affordable and casual; familiar settings with modest comfort.
3 Diamonds – Enhanced experience; comfortable and well-appointed.
4 Diamonds – Refined and upscale; notable for service and amenities.
5 Diamonds – Ultimate luxury; exceptional service, design, and experience.
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
-
-
