Check the Hotel Release Notes for updates across all Hotel APIs.

Hotel Search by Location API Reference

POST

search/properties/search

Base path:

Use this base path if you have not yet received or not migrated to the new credentials from Travelport:

Pre-production https://api.pp.travelport.com/11/hotel/

Production https://api.travelport.com/11/hotel/

Use this base path after you have migrated to the new credentials from Travelport (using .net instead of .com):

Pre-production https://api.pp.travelport.net/11/hotel/

Production https://api.travelport.net/11/hotel/

Related Content: Hotel Guide, Hotel Workflow Diagram, Hotel Search by ID API Reference

The Hotel 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 Authentication and Common Hotel API Headers.

Query Parameters

None.

Request Body

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

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.

{
  "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.

{
  "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.

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.