Sign in
hotel-search

Query Session

Query hotels within a session.

post/hotel-search/sessions/{session_id}/query

Path parameters

session_idstring uuid required

Request body

zoom_levelinteger nullable

Density hint for clustering. When provided, the server groups nearby hotels into clusters at a resolution derived from this value. When absent, no clustering — returns a flat ranked list.

cluster_thresholdinteger nullable

Minimum hotels in an H3 cell to form a cluster (default 9). Hotels in cells with fewer are returned as individual pins.

sort'relevance' | 'price' | 'star_rating' | 'review_score' | 'distance'

How to order hotel results in the list/map view.

Example request

{
  "filters": {
    "amenities": [
      "wifi",
      "pool"
    ],
    "max_price_per_night": {
      "amount": 30000,
      "currency": "USD"
    },
    "max_star_rating": 4,
    "min_price_per_night": {
      "amount": 10000,
      "currency": "USD"
    },
    "min_review_score": 7.5,
    "min_star_rating": 3,
    "refundable_only": false
  }
}

Response

Successful Response

query_idstring required
session_idstring uuid required
check_instring date required
check_outstring date required
nightsinteger required
criteria_hashstring required
total_in_areainteger required
pricing_status'pending' | 'in_progress' | 'complete' required

Tracks where we are in the live pricing lifecycle for a query.

Client polls the query endpoint and checks this to know when to stop.

hotels_pricedinteger
hotels_unavailableinteger
pricing_pool_sizeinteger
pricing_requested_countinteger
hotels_with_compare_priceinteger
retry_after_msinteger nullable
unavailable_hotel_idsinteger[]

Example response

{
  "guests": {
    "rooms": [
      {
        "adults": 2,
        "children": [
          {
            "age": 5
          }
        ]
      }
    ]
  },
  "filters": {
    "amenities": [
      "wifi",
      "pool"
    ],
    "max_price_per_night": {
      "amount": 30000,
      "currency": "USD"
    },
    "max_star_rating": 4,
    "min_price_per_night": {
      "amount": 10000,
      "currency": "USD"
    },
    "min_review_score": 7.5,
    "min_star_rating": 3,
    "refundable_only": false
  },
  "criteria": {
    "guests": {
      "rooms": [
        {
          "adults": 2,
          "children": [
            {
              "age": 5
            }
          ]
        }
      ]
    }
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.