# 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**

1. *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).

2. *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<Destination> | 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. |


## 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](../guides/error-handling) for the full business-code table.