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

Hotel Standard Search by Location API Reference

POST	search/properties/search Base path: Pre-production https://api.pp.travelport.com/11/hotel/ Production https://api.travelport.com/11/hotel/

The Hotel Standard Search by Location request searches for hotels by any one of these:

geographic coordinate information
city, state/province, and country
IATA airport or city code.

The number of properties returned is 25 per page (see pagination) unless fewer properties are in the remaining list of properties.

Request

Also see Authorization and Common Hotel API Headers.

Query Parameters

None.

Request Body

Show Request Body Table

Object

Description

Required/Optional

PropertiesQuerySearch

Top level object for request.

Includes RoomStayCandidate, SearchBy, and RateCandidates objects.

Required

CheckInDate

String. Check-in date in YYYY-MM-DD format.

Required

CheckOutDate

String. Check-out date in YYYY-MM-DD format.

Required

RequestedCurrency

String. Send the currency code to return a conversion rate for.

Rates are always returned in the currency of the hotel's location. You can use requestedCurrency to send a currency to request conversion rate information. The response then returns the CurrencyRateConversion object, which provides the conversion rate of the specified currency that can be used to calculate, independently of the API, the conversion of the rates returned in the response.

Optional

ImageSize

String. A size for the image to return, allowing you to set image quality. The following values are accepted:

ExtraLarge
Large
Medium
Small
Thumbnail

Optional

returnAllImagesInd

Element to distinguish between requesting one or all images for each property returned in the response. Boolean values of true/false. Default when missing in request is false.

Optional

returnOnlyAvailablePropertiesInd

Boolean (true/false). Used to request a list of properties with current availability for the dates requested. Default is false, meaning some properties returned in the list may have no availability. When the value is true, only properties with availability will be returned in the list and fewer than 25 properties per page may be returned. In some cases, zero properties will be returned if no properties in that group of 25 are available.

Optional

AggregatorList

Restrict the search to a specific aggregator. Accepted values are:

TVPT Travelport
BKNG Booking.com
EXPE Expedia

User must be authorized for any aggregator selected.

Optional

HotelName

String. A string of characters used to search for properties with a matching hotel name. The string must match as a substring (case insensitive) in a property's name for the property to be returned. Must be at least three characters long. Supported characters are alphanumeric, comma, period, apostrophe, hyphen, semicolon, colon, and space.

Optional

ChainCodes

Array of one to six hotel chain codes to filter property search results. Each chain code in the array must be two alpha characters.

The ChainCodes field now supports the entry of brand codes, which are expanded internally by Travelport into the associated chain codes for that brand. The current brand codes supported are:

6C	Intercontinental Hotels Group
CW	Radisson Hotel Group
EC	Exclusively Choice
EH	All Brands For Hilton
EM	All Marriott Brands
EW	Every BWH Hotel
GL	Global Hotel Alliance
HY	Hyatt Hotels And Resorts
LH	All Hyatt
LI	Louvre Hotels
PV	Preferred Hotel Group
RR	Red Roof Brands
RT	Accor Reservation Services
SN	Sonesta Collection
TC	TravelClick Inc
VH	Vantage
WR	By Wyndham Brands
WW	Worldhotels Collection

Optional

RoomStayCandidate

Top level object for information associated with room searches.

Includes GuestCounts object.

Required

GuestCounts

Top level object for guest counts.

Includes GuestCount object.

Required

GuestCount

Guest count and age(s).

Required

count

Number. Number of travelers. Must be a numeric value between 1 and 9.

Required

age

Age of traveler. Required only when request includes a child in room.

Optional

ageQualifyingCode

Required only if traveler age is relevant to a code.

Optional

SearchBy

Top level object for the types of location searches.

Includes SearchRadius object.

Required

type

String.

SearchByAirport: Send when using SearchAirport per below.

SearchByCity: Send when using SearchCity per below.

SearchByGeoLocation: Send when using Latitude and Longitude per below.

SearchByAddress: Send when using SearchAddress per below.

SearchRadius

Common object for all four types of location search.

Required

value

Number. The radius around the specified location to search. Must be a numeric value between 1 and 25. The unit of measure is specified in unitOfDistance.

Required

unitOfDistance

String. Optional object to request either miles or kilometers for the search radius from the specified location. If unitOfDistance is not specified, the search defaults to miles for properties in the United States, Myanmar, and Liberia. The search defaults to kilometers in all other countries.

Supported values:

Miles: search in miles
Kilometers: search in kilometers

Optional

SearchAirport

An airport IATA code. Must be three alpha characters.

Required for search by airport code.

SearchCity

A city IATA code. Must be three alpha characters. If no matching city code is found, airport search is automatically invoked.

Required for search by city code.

Latitude

Number. Numeric value representing latitude of search center point in degrees and decimal minutes (e.g. 39.7392).

Required for search by latitude and longitude.

Longitude

Number. Numeric value representing longitude of search center point in degrees and decimal minutes (e.g. -104.9903).

Required for search by latitude and longitude.

SearchAddress

Search by city, state/province, and country.

Includes StateProv object.

Required for search by address.

City

String. Full city name.

Required for search by address.

Country

String. Two character country code.

Required for search by address.

StateProv

String. State or province object.

Required for search by address if Country is US or CA.

value

String. Two character state or province code.

Required for search by address if Country is US or CA.

RateCandidates

An array of one to eight negotiated rate codes and / or one frequent guest number.

Includes RateCandidate object.

Optional

RateCandidate

Rate plan details and/or frequent guest number, if requesting.

Includes CustomerLoyalty object.

Optional

rateCode

String. Negotiated rate code.

Optional

masterRateCode

String. An agency-created rate code that can be translated into up to 12 negotiated rate codes.

Optional

rateCategory

For a rate category, send one or up to 8 rate categories to search for, such as Weekend or Government. If the supplier has rates available for the requested category, the response contains those rates and indicates them as such. Note that some properties do not return these rates unless explicitly requested. Categories are spelled for readability in this document. Please consult the swagger file for exact spelling. Travelport translates the category of “All” into the category set of Promotional, Package, Senior Citizen, Family Plan, Weekend, Association, Corporate, Government.

Supported values are as follows:

All
Association
Club
Convention
Corporate
Family Plan
Government
Military
Multi-level/Negotiated/Secure
Package
Promotional
Rack General
Senior Citizen
Tour
Industry/Travel Agent Rate
Weekend
Multi-day Package
Weekly
Monthly

Optional

CustomerLoyalty

String. One frequent guest number.

Optional

supplier

String. Two character hotel supplier code or brand code of the loyalty program.

Optional

value

String. Number on loyalty card.

Optional

Response

Show Response Body Table

Object	Description
PropertiesResponse	Top level object for response. Includes Properties and CurrencyRateConversion objects.
Properties	Top level object that includes pagination information for properties list. Key value pairs: totalProperties: The total number of properties returned in the search. propertiesPerPage: The number of properties returned in the current page (max 25 per page). numberOfPages: The total number of pages that can returned in the search. Includes Identifier and PropertyInfo objects.
Identifier	A key that can be used to retrieve additional pages of properties. Key value pair: value: An identifier to be sent in any subsequent Pagination request.
PropertyInfo	Each instance of PropertyInfo provides all information returned about one property Key value pairs: availability: Indicates whether the property has rooms available for the requested dates; possible values are: Open: Property has rooms/rates available that match search parameters. Other: Property has rooms/rates available that do not match search parameters. Close: Property has no rooms available. id: Property identifier composed of the chain and property codes. featuredPropertyInd: Indicates if a property has been promoted to the top of the Properties list through the featured properties program. Featured properties always have this indicator and are sorted at the top of the list when searching by IATA city/airport codes. Includes Identifier, Distance, Property, and LowestAvailableRate objects.
Identifier	Defines which supplier system returned the lowest available rate for that property. Key value pair: authority: Indicates which supplier returned the lowest available rate for that property. Supported values are: TVPT: Travelport EXPE: Expedia BKNG: Booking.com Authority is not returned if the property is closed or returns an error.
Distance	The distance from the specified search location. Key value pairs: unitofDistance: The unit of distance for the search radius around the specified location. Possible values are Miles and Kilometers. If unitOfDistance is not specified in the request, the search defaults to searching in miles for properties in the United States, Myanmar, and Liberia. The search defaults to kilometers in all other countries. value: The distance from the specified search location. The Distance object is returned in all responses but is not relevant to a search by property IDs, only for a search by location.
Property	Key value pairs: name: Text string for the name of the property. id: Property ID composed of the chain and property codes. Includes PropertyKey, Rating, GeoLocation, Image, and Address objects.
PropertyKey	Property chain code and property code. Key value pairs: chainCode: Two-character code for the chain. propertyCode: Code for the property within the hotel chain.
Rating	A hotel rating from NTM. Key value pairs: provider: Rating source. value: Rating value.
GeoLocation	Geographic coordinates of the property. Key value pairs: latitude: The numeric latitude of the property. longitude: The numeric longitude of the property.
Image	A link to an image for the property. Key value pairs: dimensionCategory : Image size category. Possible values are: S: Small M: Medium T: Thumbnail L: Large E: ExtraLarge width: Image width in pixels. height: Image height in pixels. caption: Image caption up to 128 characters. pictureCategory: The image category number. Possible values are: 1: exterior 2: lobby 3: pool 4: restaurant 5: health club 6: guestroom 7: suite 8: conference room 9: ballroom 10: golf 11: beach 12: spa 13: bar 14: recreational 21: room amenity 22: property amenity 23: business center value: A link to an image for the property.
Address	The property address information. Key value pairs: AddressLine: An array of strings for street address. Each element of the array represents an address line. City: The full city name of the property address. PostalCode: The postal code or zip code of the property address. Includes StateProv and Country objects.
StateProv	Key value pair: value: The state or providence code of the property address.
Country	Key value pairs: name: The full name of the property address's country. value: The country code of the property address
PropertyAmenity	An array of amenities such as type of breakfast, spa, and pool. Key value pairs: description: Type of amenity. code: OTA code for amenity
LowestAvailableRate	The hotel's lowest available rate for the property for the requested dates. Key value pairs: code: Code for the currency the rate is returned in. value: Amount of lowest available rate.
MaximumAvailableRate	The hotel's maximum available rate for the property for the requested dates. Key value pairs: code: Code for the currency in which the rate is returned. value: Amount of maximum available rate. authority: Indicates which supplier returned the maximum available rate for that property. Supported values are: TVPT: Travelport EXPE: Expedia BKNG: Booking.com Authority is not returned if it matches the value in PropertyInfo.Identifier.authority.
CurrencyRateConversion	CurrencyRateConversion is returned only if requestedCurrency was sent in the request. By default the Hotel APIs return all rates in the currency of the hotel's location. If requestedCurrency was sent in the request, the response returns currency conversion information per below. Includes SourceCurrency, TargetCurrency, and ConversionRate objects.
SourceCurrency	The currency code based on the location of the hotel and used for all rates in the response. Key value pairs: decimalPlace: Number of decimal places for the currency value. value: Currency code.
TargetCurrency	Currency code sent in the request in requestedCurrency. Key value pairs: decimalPlace: Number of decimal places value: Currency code.
ConversionRate	Current conversion rate of the user-specified currency (the TargetCurrency value). Key value pair: value: Conversion rate of SourceCurrency value to TargetCurrency value. This value can be used to calculate, independently of the API, conversion for the rates in the response.

Example Request

The example below searches for properties by city, state or province, and country.

Show Example Request

{
  "PropertiesQuerySearch": {
    "CheckInDate": "2021-04-01",
    "CheckOutDate": "2021-04-04",
    "ImageSize": "Large",
    "RequestedCurrency": "EUR",
    "RoomStayCandidate": [
      {
        ”type": "RoomStayCandidate",
        "GuestCounts": {
          ”type": "GuestCounts",
          "GuestCount": [
            {
              ”type": "GuestCount",
              "count": 2
            }
          ]
        }
      }
    ],
    "SearchBy": {
      ”type": "SearchByAddress",
      "SearchRadius": {
        "value": 5,
        "unitOfDistance": "Miles"
      },
      "SearchAddress": {
        ”type": "SearchAddress",
        "City": "Denver",
        "StateProv": {
          "value": "CO"
        },
        "Country": "US"
      }
    }
  }
}

Example Response

The following example response has been edited for brevity to show five instances of PropertyInfo. Depending on availability, most responses return more instances.

Show Example Response

{
  "PropertiesResponse": {
    "Properties": {
      ”type": "Properties",
      "totalProperties": 82,
      "propertiesPerPage": 25,
      "Identifier": {
        "value": "9dc1a948-5e0e-4d47-81a9-485e0e0d4712"
      },
      "PropertyInfo": [
        {
          ”type": "PropertyInfo",
          "availability": "Close",
          "id": "PH-B0396",
          "Distance": {
            "unitOfDistance": "Miles",
            "value": 0
          },
          "Property": {
            ”type": "PropertyDetail",
            "name": "THE ART A HOTEL DENVER LVX",
            "id": "PH-B0396",
            "PropertyKey": {
              "chainCode": "PH",
              "propertyCode": "B0396"
            },
            "Rating": [
              {
                "provider": "NTM",
                "value": "0"
              }
            ],
            "GeoLocation": {
              "latitude": "39.735297",
              "longitude": "-104.98741"
            },
            "Address": {
              ”type": "Address",
              "AddressLine": [
                "1201 Broadway"
              ],
              "City": "DENVER",
              "StateProv": {
                "value": "CO"
              },
              "Country": {
                "value": "US"
              },
              "PostalCode": "80203"
            }
          }
        },
        {
          ”type": "PropertyInfo",
          "availability": "Open",
          "id": "SI-58960",
          "Identifier": {
            "authority": "TVPT"
          },
          "Distance": {
            "unitOfDistance": "Miles",
            "value": 0
          },
          "Property": {
            ”type": "PropertyDetail",
            "name": "SHERATON DENVER DOWNTOWN",
            "id": "SI-58960",
            "PropertyKey": {
              "chainCode": "SI",
              "propertyCode": "58960"
            },
            "Rating": [
              {
                "provider": "NTM",
                "value": "3"
              }
            ],
            "GeoLocation": {
              "latitude": "39.742055",
              "longitude": "-104.989293"
            },
            "Image": [
              {
                "dimensionCategory": "L",
                "caption": "Exterior",
                "pictureCategory": 1,
                "value": "https://travelport.leonardocontentcloud.com/imageRepo/6/0/100/8/898/dends-exterior-9244-hor-clsc_I.jpg"
              }
            ],
            "Address": {
              ”type": "Address",
              "AddressLine": [
                "1550 COURT PLACE"
              ],
              "City": "DENVER",
              "StateProv": {
                "value": "CO"
              },
              "Country": {
                "value": "US"
              },
              "PostalCode": "80202"
            }
          },
          "LowestAvailableRate": {
            "code": "USD",
            "value": 260.1
          }
        },
        {
          ”type": "PropertyInfo",
          "availability": "Close",
          "id": "WK-58731",
          "Distance": {
            "unitOfDistance": "Miles",
            "value": 0
          },
          "Property": {
            ”type": "PropertyDetail",
            "name": "WARWICK DENVER HOTEL",
            "id": "WK-58731",
            "PropertyKey": {
              "chainCode": "WK",
              "propertyCode": "58731"
            },
            "Rating": [
              {
                "provider": "NTM",
                "value": "3"
              }
            ],
            "GeoLocation": {
              "latitude": "39.7441",
              "longitude": "-104.9836"
            },
            "Image": [
              {
                "dimensionCategory": "L",
                "caption": "Balcony View",
                "pictureCategory": 1,
                "value": "https://travelport.leonardocontentcloud.com/imageRepo/2/0/65/443/662/Balcony_View_-_med_I.jpg"
              }
            ],
            "Address": {
              ”type": "Address",
              "AddressLine": [
                "1776 Grant Street"
              ],
              "City": "DENVER",
              "StateProv": {
                "value": "CO"
              },
              "Country": {
                "value": "US"
              },
              "PostalCode": "80203"
            }
          }
        },
        {
          ”type": "PropertyInfo",
          "availability": "Open",
          "id": "AK-21793",
          "Identifier": {
            "authority": "TVPT"
          },
          "Distance": {
            "unitOfDistance": "Miles",
            "value": 0
          },
          "Property": {
            ”type": "PropertyDetail",
            "name": "BROWN PALACE HOTEL AUTOGRAPH",
            "id": "AK-21793",
            "PropertyKey": {
              "chainCode": "AK",
              "propertyCode": "21793"
            },
            "Rating": [
              {
                "provider": "NTM",
                "value": "4"
              }
            ],
            "GeoLocation": {
              "latitude": "39.744",
              "longitude": "-104.9877"
            },
            "Image": [
              {
                "dimensionCategory": "L",
                "caption": "Historic Hotel Tours",
                "pictureCategory": 1,
                "value": "https://travelport.leonardocontentcloud.com/imageRepo/7/0/109/855/585/denak-hotels-7268-hor-clsc_I.jpg"
              }
            ],
            "Address": {
              ”type": "Address",
              "AddressLine": [
                "321 17TH ST"
              ],
              "City": "DENVER",
              "StateProv": {
                "value": "CO"
              },
              "Country": {
                "value": "US"
              },
              "PostalCode": "80202"
            }
          },
          "LowestAvailableRate": {
            "code": "USD",
            "value": 250
          }
        },
        {
          ”type": "PropertyInfo",
          "availability": "Open",
          "id": "YZ-C7704",
          "Identifier": {
            "authority": "TVPT"
          },
          "Distance": {
            "unitOfDistance": "Miles",
            "value": 0
          },
          "Property": {
            ”type": "PropertyDetail",
            "name": "STAYBRIDGE STES DOWNTOWN",
            "id": "YZ-C7704",
            "PropertyKey": {
              "chainCode": "YZ",
              "propertyCode": "C7704"
            },
            "Rating": [
              {
                "provider": "NTM",
                "value": "2"
              }
            ],
            "GeoLocation": {
              "latitude": "39.7404",
              "longitude": "-104.9926"
            },
            "Image": [
              {
                "dimensionCategory": "L",
                "caption": "The all new Staybridge Suites Denver Downtown-Actu",
                "pictureCategory": 1,
                "value": "https://travelport.leonardocontentcloud.com/imageRepo/5/0/91/808/883/DENCA_4732251338_I.jpg"
              }
            ],
            "Address": {
              ”type": "Address",
              "AddressLine": [
                "333 WEST COLFAX AVENUE"
              ],
              "City": "DENVER",
              "StateProv": {
                "value": "CO"
              },
              "Country": {
                "value": "US"
              },
              "PostalCode": "80204"
            }
          },
          "LowestAvailableRate": {
            "code": "USD",
            "value": 185.38
          }
        },
      ]
    },
    "Result": {
      "Warning": [
        {
          ”type": "Warning",
          "StatusCode": 99,
          "Message": "Rates unavailable for 7 properties."
        }
      ]
    },
    "CurrencyRateConversion": [
      {
        "SourceCurrency": {
          "decimalPlace": 2,
          "value": "USD"
        },
        "TargetCurrency": {
          "decimalPlace": 2,
          "value": "EUR"
        },
        "ConversionRate": {
          "value": 0.846
        }
      }
    ]
  }
}

Error Messages

Search returns an error when no offers are returned for a request.

Show Error Messages

SourceCode	StatusCode (HTTP code)	Message
	400	Property Code is invalid, must be alphanumeric.
	400	Property Code is a required field.
	400	Chain code '%s' is invalid, must be 2 alphabetic characters.
	400	Chain code is a required field.
	400	Please provide no more than 6 chain codes.
	400	Hotel name is invalid, must be at least 3 characters.
	400	Hotel name can contain alphanumeric, comma, period, apostrophe, hyphen, semicolon, colon, and space.
	400	Invalid City, StateProv and Country combination. Please check and try again.
	400	At least one Property Id is required.
	400	Chain code is invalid, must be 2 alphabetic characters.
	400	Chain code is a required field.
	400	Response can be returned for first 25 valid properties, excluding the rest properties.
	400	Invalid RateCodes, should be alphanumeric.
	400	Processing NegotiatedRates for first 8 valid RateCodes.
	400	Negotiated Rates Service is currently turned off.
	400	Property not allowed: User unauthorized to view content for requested chain code.
	400	Not able to reach IDM Authorization atomic or Authorization cannot be identified due to insufficient inputs.
	400	Chain code 'null' is invalid, must be 2 alphabetic characters.
	400	SearchRadius value is missing.
	400	SearchAirport Code should be 3 letters.
	400	StateProv is a required field if latitude or longitude is not provided.
	400	Country is a required field if latitude or longitude is not provided.
	400	City is a required field if latitude or longitude is not provided.
	400	checkindate is not valid.
	400	checkindate cannot be less than currentdate.
	400	checkoutdate cannot be equal to checkindate.
	400	numberOfGuests should be numeric.
	400	numberOfGuests should be between 1 and 9.
	400	numberOfGuests should be a whole number.
	400	latitude is invalid.
	400	longitude is invalid.
	400	unitOfDistance value should be KILOMETERS, MILES
	400	Sort value should be STARRATING or PROXIMITY.
	400	Valid range for SearchRadius is 1 to 25.
	400	SearchRadius should be a whole number.
	401	Unauthorised user.
	401	Property not allowed: User unauthorized to view content for requested chain code.
	404	No Properties found.
	404	No Hotels found matching the input of SearchAirport Code
	500	Error in invokeTranslationService.
	500	Unable to process request. Exception occurred.
	500	Error occurred while processing returned non-featured properties.
	500	Error occurred while processing more returned non-featured properties.
	99	Response can be returned for first 25 valid properties, excluding the rest properties.