3. API Reference

Destinations

POST /api/search/destinations

Returns destination records - either standard or detailed - selected by a parent destination ancestor ID or by a country code. The data is hierarchical and intended for hotel booking clients.

Two ways to query

By parent destination ID - supply parentDestinationId to retrieve the immediate children of that destination. Useful when walking a location tree (for example, the cities that sit under a state).
By country code - supply countryCode in ISO 3166-1 alpha-2 form (for example US, CN) to retrieve the top-level destinations of that country. When countryCode is present, parentDestinationId is disregarded.

Levels of detail returned

standard (the default): metadata plus basic hierarchy for each region.
details: metadata plus coordinates and the complete hierarchy for each region.

Typical uses

Populating location pickers on booking forms.
Progressive location narrowing (country, then state, then city).
Autocomplete over geographic search.

Performance

Responses are served from cache.
A large country can yield a high destination count; paginate in the UI if needed.

Request headers

Header	Required	Description
`Client-Request-Timestamp`	No	Unix timestamp recorded by the client at the moment it began sending the request.
`IP`	No	Client IP address; both IPv4 and IPv6 are accepted.
`Language`	No	IETF BCP 47 language tag, for example "en" or "en-US". Defaults to "en-US" when omitted. Reference: https://masonreview.com/posts/ietf-bcp-47-language-tags/
`Market`	No	Point-of-sale market for this call, as an ISO 3166-1 alpha-2 country code. Required only when your account carries a market restriction: an allow-list cannot admit a market you have not stated, so such an account refuses calls that omit it.
`Request-Id`	No	Identifies this single request; the value must not repeat across requests.
`Trace-Id`	No	Correlates a group of related requests for tracing.
`User-Ref`	No	Your own identifier for the person on whose behalf this call is made. Required only once named users have been authorised on your account, after which every call must identify one and is authorised against that user's scopes as well as the key's.
`Authorization`	Yes	Bearer credential. The value begins with the literal prefix "Bearer " and the token is obtained from the Ticket response. The Ticket endpoint itself does not require this header.

Request body

Field	Type	Required	Description
`countryCode`	string	No	The country code, for example "US".
`parentDestinationId`	string	No	Unique identifier of the ancestor destination. This field is disregarded when a country code is supplied.
`include`	enum	No	Selects how much detail the response carries. Permitted values are "standard" and "details"; "standard" is used when the field is omitted. Allowed: `standard`, `details`.
`filterEmptyCities`	boolean	No	Drop cities that have no hotels. Treated as true when the field is omitted.
`minHotelCount`	integer	No	Lowest hotel count a city must reach to be returned. Treated as 1 when the field is omitted.

Example request

json

{
  "countryCode": "AE"
}

Response

Successful calls return the standard envelope. code is 0 on success — check it rather than the HTTP status alone, because some business failures are delivered with HTTP 200.

Field	Type	Required	Description
`code`	integer	No
`msg`	string	No
`data`	hotel.search.protocol.DestinationsResp	No
`data.destinations[]`	array	No	Carries the region records.
`data.destinations[].id`	string	No
`data.destinations[].type`	hotel.geography.domain.DestinationType	No	Classification of a destination record. - `DestinationType_Unknown` (`0`): no description supplied in the source. - `DestinationType_Continent` (`1`): a large landmass such as Europe, Asia or South America. The region summary section lists the continents. - `DestinationType_Country` (`2`): a nation-state such as the United States, Australia or Germany. Countries/regions here are drawn geographically rather than politically - Guadeloupe, for instance, is a French department in the Caribbean that belongs politically to France yet forms its own geographic entity. The region summary section lists the countries/regions. - `DestinationType_ProvinceState` (`3`): an administrative division inside a country, such as California or New South Wales. Lower-level administrative divisions - counties and provinces within a country/region - fall under this type too. - `DestinationType_HighLevelRegion` (`4`): a tourist region, such as the Upper Rhine in Germany or the wine country in California. - `DestinationType_MultiCityVicinity` (`5`): a large metropolitan area covering a major city together with its surrounding suburbs, such as Cairo and the areas around it. Polygon boundaries for these are drawn broadly according to tourist value. - `DestinationType_City` (`6`): an urban area, such as Bellevue and Washington. A large metropolitan area can contain a city - London, for example - in which case the city covers a smaller footprint than the corresponding multi_city_vicinity. Each accommodation contracted with Expedia must be tied to a city, since the city is the base unit of geographic coverage. City polygon boundaries follow official administrative sources. - `DestinationType_Neighborhood` (`7`): a geographic area smaller than a city, such as the old town in Bonn, Germany. Neighborhood polygon boundaries are drawn by tourist value rather than by administrative definition. - `DestinationType_Airport` (`8`): an airport, such as LHR (London Heathrow). - `DestinationType_PointOfInterest` (`9`): a place such as a museum, convention center, beach or park. The list covers not only well-known tourist attractions but a broader set of venues, such as the Shanghai Exhibition Center, the Texas State Capitol or the Prague Zoo. - `DestinationType_TrainStation` (`10`): a train station, such as Grand Central Terminal in New York. - `DestinationType_MetroStation` (`11`): a subway station, such as Avtovo Station in St. Petersburg, Russia. - `DestinationType_BusStation` (`12`): a bus station, such as the Port Authority Bus Terminal in New York State, USA. Allowed: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`.
`data.destinations[].name`	I18N	No	Localised name.
`data.destinations[].name.en`	string	No	English; the default system language.
`data.destinations[].name.zh`	string	No	Chinese (中文).
`data.destinations[].name.ar`	string	No	Arabic (اللغة العربية).
`data.destinations[].nameFull`	I18N	No	Fully qualified localised name, for example "Springfield, Missouri, United States of America".
`data.destinations[].nameFull.en`	string	No	English; the default system language.
`data.destinations[].nameFull.zh`	string	No	Chinese (中文).
`data.destinations[].nameFull.ar`	string	No	Arabic (اللغة العربية).
`data.destinations[].countryCode`	string	No	ISO 3166-1 alpha-2 country code. Reference: https://www.iso.org/obp/ui/#search
`data.destinations[].coordinates`	Coordinates	No	Location descriptor.
`data.destinations[].coordinates.centerLat`	number	No
`data.destinations[].coordinates.centerLng`	number	No
`data.destinations[].coordinates.boundingPolygon`	BoundingPolygon	No
`data.destinations[].extra`	hotel.geography.domain.DestinationExtra	No
`data.destinations[].extra.cityName`	I18N	No	City name.
`data.destinations[].extra.provinceName`	I18N	No	Province name.
`data.destinations[].extra.continentName`	I18N	No	Continent name.
`data.destinations[].extra.hotelCount`	integer	No	Hotel count.
`data.destinations[].countryName`	I18N	No	Localised string set. Keys are fixed language codes.
`data.destinations[].countryName.en`	string	No	English; the default system language.
`data.destinations[].countryName.zh`	string	No	Chinese (中文).
`data.destinations[].countryName.ar`	string	No	Arabic (اللغة العربية).
`data.destinations[].destinationName`	I18N	No	Localised string set. Keys are fixed language codes.
`data.destinations[].destinationName.en`	string	No	English; the default system language.
`data.destinations[].destinationName.zh`	string	No	Chinese (中文).
`data.destinations[].destinationName.ar`	string	No	Arabic (اللغة العربية).
`data.destinations[].parentDestinationName`	I18N	No	Localised string set. Keys are fixed language codes.
`data.destinations[].parentDestinationName.en`	string	No	English; the default system language.
`data.destinations[].parentDestinationName.zh`	string	No	Chinese (中文).
`data.destinations[].parentDestinationName.ar`	string	No	Arabic (اللغة العربية).
`data.destinations[].parentDestinationId`	string	No	Code of the parent region: for a city this is the province code, for a province it is the country code.

Example response

json

{
  "code": 0,
  "msg": "string",
  "data": {
    "destinations": [
      {
        "id": "string",
        "type": 0,
        "name": {
          "en": "string",
          "zh": "string",
          "ar": "string"
        },
        "nameFull": {
          "en": "string",
          "zh": "string",
          "ar": "string"
        },
        "countryCode": "string",
        "coordinates": {
          "centerLat": 0,
          "centerLng": 0,
          "boundingPolygon": {
            "type": "string",
            "coordinates": []
          }
        },
        "extra": {
          "cityName": {
            "en": "string",
            "zh": "string",
            "ar": "string"
          },
          "provinceName": {
            "en": "string",
            "zh": "string",
            "ar": "string"
          },
          "continentName": {
            "en": "string",
            "zh": "string",
            "ar": "string"
          },
          "hotelCount": 0
        },
        "countryName": {
          "en": "string",
          "zh": "string",
          "ar": "string"
        },
        "destinationName": {
          "en": "string",
          "zh": "string",
          "ar": "string"
        },
        "parentDestinationName": {
          "en": "string",
          "zh": "string",
          "ar": "string"
        },
        "parentDestinationId": "string"
      }
    ]
  }
}

Failure responses

HTTP	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
429	Too Many Requests

Every failure uses the { code, msg } envelope. See Error handling for the full business-code table.

Code samples

bash

curl -X POST https://api-test.ttdbooking.com/api/search/destinations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TICKET" \
  -H "Request-Id: $(uuidgen)" \
  -d '{
    "countryCode": "AE"
  }'

Try it

POST /api/search/destinations

Base URLThe published API hosts, or a localhost origin for local testing.Request body

A ticket will be fetched with ttdbooking_api_demo.