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. |
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
{
"destinationId": "804028047",
"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 | Unique identifier of this hotel. |
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. |
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
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": "804028047",
"countryCode": "AE",
"page": {
"pageNum": 1,
"pageSize": 20,
"cursor": 0
}
}'Try it
Try it
POST /api/search/hotelsMetadataA ticket will be fetched with ttdbooking_api_demo.