3. API Reference

HotelsMetadata

POST /api/search/hotelsMetadata

Returns paginated hotel metadata for a single destination.

Use this endpoint to enumerate the hotels that belong to a destination and pull their descriptive attributes (identifier, localised name and address, star rating, coordinates, logo image). It is aimed at catalogue and content workflows rather than at live availability.

Primary use cases

Browsing a hotel catalogue one destination at a time
Populating hotel listings inside a CMS
Enriching search interfaces with hotel metadata

Required parameters

destinationId — the unique identifier of the destination

Integration notes

Intended for content and catalogue operations
Suitable for building hotel-selection UIs
Supports incremental synchronisation of hotel metadata

Request headers

Header	Required	Description
`Client-Request-Timestamp`	No	Time at which the client began sending the request, expressed as a Unix timestamp.
`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	Identifier for this single request. Values must not be reused across requests.
`Trace-Id`	No	Correlation identifier used to trace a group of related requests.
`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 must start with "Bearer " followed by the token returned by the Ticket endpoint. The Ticket endpoint itself does not require this header.

Request body

Field	Type	Required	Description
`destinationId`	string	Yes	Unique identifier of the destination (region) to list hotels for — the `id` of a node returned by Destinations, which is a UUID rather than a numeric code.
`countryCode`	string	No	Country code associated with this listing.
`page`	PageReq	No	Pagination parameters for the request. The default page size differs by endpoint — HotelsMetadata returns 20 per page when `pageSize` is omitted, QueryOrders returns 100 — so send it explicitly if the size matters to you.
`page.pageNum`	integer	No	Page number to retrieve. The first page is 1; a value below 1 is treated as 1 rather than rejected.
`page.pageSize`	integer	No	Number of items per page, up to 100. A larger value is rejected with code 100000400. Defaults to 20 on HotelsMetadata and 100 on QueryOrders.
`page.cursor`	integer	No	Cursor pointing at the next page.

Example request

json

{
  "destinationId": "0192f3a7-5c41-7e88-b3d2-9a1c4e6f0b57",
  "countryCode": "AE",
  "page": {
    "pageNum": 1,
    "pageSize": 20,
    "cursor": 0
  }
}

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.HotelsMetadataListResp	No
`data.hotelsMetadata[]`	array	No	List of hotel metadata entries.
`data.hotelsMetadata[].hotelId`	string	No	Identifier of this property as the source that served it names it. Accepted back on `hotelIds`, but not stable across sources — key your catalogue on `ttdHotelId`.
`data.hotelsMetadata[].ttdHotelId`	string	No	The platform's stable, client-facing property code — the same value the hotel-catalogue file publishes as `ttdHotelId`. One property is one code, and unlike `hotelId` it does not change with the supplier that served this result, so it is the id to key your catalogue on. Present whenever the property is matched to our master catalogue. Accepted anywhere a hotel id is sent.
`data.hotelsMetadata[].destinationId`	string	No	Destination identifier this hotel belongs to. Source note: index.
`data.hotelsMetadata[].name`	I18N	No	Hotel name, localised.
`data.hotelsMetadata[].name.en`	string	No	English; the default system language.
`data.hotelsMetadata[].name.zh`	string	No	Chinese (中文).
`data.hotelsMetadata[].name.ar`	string	No	Arabic (اللغة العربية).
`data.hotelsMetadata[].rating`	number	No	Hotel rating, in the range [0.0, 5.0].
`data.hotelsMetadata[].address`	I18N	No	Localised string set. Keys are fixed language codes.
`data.hotelsMetadata[].address.en`	string	No	English; the default system language.
`data.hotelsMetadata[].address.zh`	string	No	Chinese (中文).
`data.hotelsMetadata[].address.ar`	string	No	Arabic (اللغة العربية).
`data.hotelsMetadata[].latlngCoordinator`	LatlngCoordinator	No
`data.hotelsMetadata[].latlngCoordinator.google`	Latlng	Yes
`data.hotelsMetadata[].latlngCoordinator.gaode`	Latlng	No
`data.hotelsMetadata[].logoURL`	string	No
`data.page`	PageResp	No	Pagination data returned with the response.
`data.page.total`	integer	No	Total number of items. A value of 0 means there are no items, or that totals are not supported for this query.
`data.page.hasMore`	boolean	No	Indicates whether further items remain to be fetched.

Example response

json

{
  "code": 0,
  "msg": "string",
  "data": {
    "hotelsMetadata": [
      {
        "hotelId": "string",
        "ttdHotelId": "TTD-1000001",
        "destinationId": "0192f3a7-5c41-7e88-b3d2-9a1c4e6f0b57",
        "name": {
          "en": "Jumeirah Beach Hotel"
        },
        "rating": 4.5,
        "address": {
          "en": "Millenium Al Barsha"
        },
        "latlngCoordinator": {
          "google": {
            "lat": 0,
            "lng": 0
          },
          "gaode": {
            "lat": 0,
            "lng": 0
          }
        },
        "logoURL": "https://cdn.example.com/hotel/461850557_1.jpg"
      }
    ],
    "page": {
      "total": 100,
      "hasMore": true
    }
  }
}

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/hotelsMetadata \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TICKET" \
  -H "Request-Id: $(uuidgen)" \
  -d '{
    "destinationId": "0192f3a7-5c41-7e88-b3d2-9a1c4e6f0b57",
    "countryCode": "AE",
    "page": {
      "pageNum": 1,
      "pageSize": 20,
      "cursor": 0
    }
  }'

Try it

POST /api/search/hotelsMetadata

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

A ticket will be fetched with ttdbooking_api_demo.