Hotel 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/

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 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.	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 for. 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: Large Medium Small Thumbnail	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.	Optional
RoomStayCandidate	Top level object for information associated with room searches.	Required
GuestCounts	Top level object for guest counts.	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. SearchByGeoLocation: Send when using Latitude and Longiture per below. SearchByAddress: Send when using SearchAddress per below.
SearchRadius	Common object for all three 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 or city IATA code. Must be three alpha characters.	Required for search by airport or 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
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). 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: Small Medium Thumbnail Large 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 pair: name: The full name of the property address's country. value: The country code of the property address
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.
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.