Overview

The Merchandising API Region Details service allows travel buyers to retrieve geographical hierarchy information used across hotel content and search operations.

The API supports retrieving:

• Countries
• States / Provinces
• Cities
• Full region hierarchy data

This information can be used for:

• Destination filtering
• Location search
• Static region mapping
• Search autocomplete
• Internal region normalization

Endpoint

https://sandbox-api-mtd.hoteltrader.com/distribution/graphql

Authentication

The Merchandising API uses HTTP Basic Authentication.

Authorization: Basic base64(username:password)

Region APIs Overview

API	Description
countries	Returns all available countries.
states	Returns all states/provinces for a country.
cities	Returns cities for a country and optional state.
regionHierarchies	Returns complete country/state/city hierarchy data.

Get Countries

Example Request

curl --location 'https://sandbox-api-mtd.hoteltrader.com/distribution/graphql' \
--header 'Authorization: Basic <BASE64_CREDENTIALS>' \
--header 'Content-Type: application/json' \
--data '{
  "query":"query {
    countries {
      countryCode
      countryName
    }
  }",
  "variables":{}
}'

Response Structure

{
  "data": {
    "countries": [
      {
        "countryCode":"US",
        "countryName":"United States"
      }
    ]
  }
}

Country Object

Field	Type	Description
countryCode	String	Country code.
countryName	String	Country name.

Get States / Provinces

Example Request

curl --location 'https://sandbox-api-mtd.hoteltrader.com/distribution/graphql' \
--header 'Authorization: Basic <BASE64_CREDENTIALS>' \
--header 'Content-Type: application/json' \
--data '{
  "query":"query States($countryCode: String!) {
    states(countryCode: $countryCode) {
      stateCode
      stateName
    }
  }",
  "variables":{
    "countryCode":"US"
  }
}'

Request Variables

Variable	Type	Required	Description
countryCode	String	Yes	Country code for which states should be returned.

Response Structure

{
  "data": {
    "states": [
      {
        "stateCode":"NY",
        "stateName":"New York"
      }
    ]
  }
}

State Object

Field	Type	Description
stateCode	String	State or province code.
stateName	String	State or province name.

Get Cities

Example Request

curl --location 'https://sandbox-api-mtd.hoteltrader.com/distribution/graphql' \
--header 'Authorization: Basic <BASE64_CREDENTIALS>' \
--header 'Content-Type: application/json' \
--data '{
  "query":"query Cities($countryCode: String!, $stateCode: String) {
    cities(countryCode: $countryCode, stateCode: $stateCode) {
      cityName
      stateCode
      stateName
    }
  }",
  "variables":{
    "countryCode":"US",
    "stateCode":"NY"
  }
}'

Request Variables

Variable	Type	Required	Description
countryCode	String	Yes	Country code.
stateCode	String	No	State or province code.

Response Structure

{
  "data": {
    "cities": [
      {
        "cityName":"New York",
        "stateCode":"NY",
        "stateName":"New York"
      }
    ]
  }
}

City Object

Field	Type	Description
cityName	String	City name.
stateCode	String	State or province code.
stateName	String	State or province name.

Get Full Region Hierarchy

The regionHierarchies query returns the complete country → state → city hierarchy.

This endpoint is useful for:

• Full destination ingestion
• Static geographical mapping
• Offline region database creation
• Search indexing

Example Request

curl --location 'https://sandbox-api-mtd.hoteltrader.com/distribution/graphql' \
--header 'Authorization: Basic <BASE64_CREDENTIALS>' \
--header 'Content-Type: application/json' \
--data '{
  "query":"query {
    regionHierarchies {
      dataLoadType
      timestamp
      resumeKey
      regionHierarchies {
        cityID
        cityName
        stateCode
        stateName
        countryCode
        countryName
      }
    }
  }",
  "variables":{}
}'

Region Hierarchy Response Structure

{
  "data": {
    "regionHierarchies": {
      "dataLoadType":"FULL",
      "timestamp":"2026-05-11T08:15:37Z",
      "resumeKey":null,
      "regionHierarchies": []
    }
  }
}

Region Hierarchy Metadata

Field	Type	Description
dataLoadType	String	Type of data load returned.
timestamp	DateTime	UTC timestamp of response generation.
resumeKey	String	Pagination token if additional records exist.
regionHierarchies	Array	List of hierarchy records.

Region Hierarchy Object

Field	Type	Description
cityID	Long	Internal city identifier.
cityName	String	City name.
stateCode	String	State or province code.
stateName	String	State or province name.
countryCode	String	Country code.
countryName	String	Country name.

Pagination

The regionHierarchies endpoint supports pagination using resumeKey.

If additional records exist:

"resumeKey":"Mjk1OjI="

If all records are returned:

"resumeKey":null

Example Region Hierarchy Response

{
  "cityID":null,
  "cityName":"Miami",
  "stateCode":"FL",
  "stateName":"Florida",
  "countryCode":"US",
  "countryName":"United States"
}

Common Integration Flow

Destination Hierarchy Synchronization

1. Retrieve all countries.
2. Retrieve states for each country.
3. Retrieve cities for each state.
4. Optionally use regionHierarchies for bulk synchronization.

HTTP Status Codes

Status	Meaning
200	Successful request.
400	Invalid request.
401	Authentication failed.
403	Forbidden.
500	Internal server error.