HotelList

POST /api/search/hotelList

Returns hotels matching a set of search criteria — destination, stay dates and guest configuration — with optional per-hotel room availability and pricing.

Three ways to drive the search are supported:

1. By specific SupplierHotelList — pass explicit hotel IDs to fetch detail for exactly those properties.
2. By destination — search within a region, addressed either by destinationId or by destinationName.
3. By location — return hotels near a point, ranked by distance.

Required parameters

• checkIn / checkOut — the stay dates.
• roomOccupancies — one entry per room, each carrying adultCount and optional childrenAges. At least one entry is required.
• at least one of destinationId, destinationName or hotelIds — how the search is scoped. A body carrying none of the three is rejected.

Optional parameters

• destinationId — region identifier for a location-scoped search.
• destinationName — region name; the server resolves it to an ID.
• hotelIds — explicit hotel IDs to retrieve.
• maxRatesPerHotel — cap on room rates returned per hotel; 0 (the default) is uncapped.
• sortBy — result ordering (price-asc, price-desc, rating-desc, distance-asc).
• pageNum / pageSize / cursor — pagination controls. They are flat top-level fields on this endpoint; the nested page object belongs to HotelsMetadata, not here. pageSize defaults to 50 and is capped at 200; a larger value is rejected rather than clamped.

What comes back

• A hotel list carrying core property information.
• Room availability and pricing, when requested.
• Pagination metadata for large result sets.
• A session identifier that ties the search context together.
• basic.statusRemark / basic.notices / basic.emptyReason — why a result is empty or incomplete. See "Empty results" below.

Empty results

{ "list": [], "total": 0 } has two causes that need opposite responses, and on its own it cannot tell you which you have hit:

1. The suppliers were asked and had nothing. Genuine zero availability — try other dates or another property. basic.emptyReason is ABSENT.
2. No supplier answered, or none was asked at all. A configuration state on our side. Retrying the same request, or changing the dates or the destination, cannot change it. basic.emptyReason.code is present and says which.

basic.emptyReason.code is one of:

• NO_SUPPLIER_ENABLED — no supplier is currently enabled for hotel search.
• NO_SUPPLIER_PERMITTED — suppliers are enabled, but none may serve your account on this search.
• ALL_SUPPLIERS_EXCLUDED — every candidate was excluded before the search ran, by a market, currency, language or inventory restriction.
• NO_SUPPLIER_ANSWERED — suppliers were called and every one of them failed. This is the only one of the four worth retrying.

basic.statusRemark carries the same thing as one human-readable sentence, suitable for a log line or an operator-facing message.

basic.emptyReason.suppliers — WHICH supplier failed and why — is disclosed only to accounts entitled to the supplier breakdown. Most integrations will never see it, and its absence is not an error: the code and the statusRemark are complete without it.

basic.notices is separate and belongs to a search that WORKED: it lists what the response does not contain when the result is real but not complete (a destination expansion that hit its cap, properties dropped because they could not be priced in the requested currency). It is not emitted alongside emptyReason — on an empty response there is no partial result for it to qualify, and statusRemark already carries the explanation.

All four fields are additive and optional. A client that ignores them behaves exactly as it did before they existed.

Typical uses

• Powering a hotel booking search UI.
• Browsing the inventory of a destination.
• Looking up one or more known properties.
• Suggesting hotels near a given point.

Request headers

Request body

Example request

{
  "hotelIds": [
    "461850557",
    "118062388"
  ],
  "maxRatesPerHotel": 3,
  "checkIn": "2026-01-01",
  "checkOut": "2026-01-03",
  "countryCode": "US",
  "residencyCode": "US",
  "nationalityCode": "US",
  "roomOccupancies": [
    {
      "adultCount": 2,
      "childrenAges": [
        2
      ]
    }
  ],
  "destinationId": "0192f3a7-5c41-7e88-b3d2-9a1c4e6f0b57",
  "destinationName": "Dubai",
  "pageNum": 1,
  "pageSize": 50,
  "cursor": 0,
  "sortBy": "price-desc"
}

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.

Example response

{
  "code": 0,
  "msg": "string",
  "data": {
    "list": [
      {
        "id": "461850557",
        "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",
        "minPrice": {
          "amount": 100,
          "currency": "USD"
        },
        "minPricesByCurrency": [
          {
            "amount": 700,
            "currency": "CNY"
          },
          {
            "amount": 85,
            "currency": "EUR"
          }
        ],
        "isAvailable": true,
        "rooms": [
          {
            "roomTypeId": "string",
            "roomTypeName": {},
            "hotelId": "string",
            "rates": []
          }
        ]
      }
    ],
    "basic": {
      "destination": {
        "id": "0192f3a7-5c41-7e88-b3d2-9a1c4e6f0b57",
        "name": {
          "en": "Dubai"
        }
      },
      "sessionId": "374337a797454a344ad999c7730da01c",
      "statusRemark": "No supplier was searched for this request: no supplier is currently enabled for hotel search. This is a configuration state, not an absence of availability — retrying, or changing the dates or destination, will not change it. Contact your account manager.",
      "notices": [
        "Showing the first 200 of 4318 properties matching \"United Arab Emirates\". Narrow to a city or area for full coverage."
      ],
      "emptyReason": {
        "code": "NO_SUPPLIER_ENABLED",
        "suppliers": [
          {
            "supplierCode": "MOCK",
            "reason": "TIMEOUT: supplier did not respond within 20000 ms"
          }
        ]
      }
    },
    "total": 100,
    "hasMore": true
  }
}

Failure responses

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