Search hotels
POST /v1/hotels/search · MCP tool: search_hotels
Find hotels by country and either city or latitude/longitude, with optional hotel filters; compare provider stay totals. Coordinates use the supplied center without a place lookup. Default order: nearest 5 km bands first, then greatest Brek price advantage over the cheapest other provider within each band. One search call ($0.04 after signup credits). Coverage reports failures and truncation. More pages of the same 10-minute quote session are free.
Run this tool on HotelUse · Download full captured response
How it works
Send a city or latitude/longitude and stay dates. HotelUse uses explicit coordinates directly, or resolves the city through Auto Suggest, starts with matching static records in a 20 km core circle, and expands to 40 km then 60 km only while fewer than 50 matching static candidates are found. It then calls providers once for the final candidate set using their mapped hotel IDs. An explicit max_distance_km is a hard limit and disables expansion. The response geographic_scope.recall lists attempted radii and why expansion stopped. Expansion shares the request deadline; if a wider catalog query times out, only the last completed scope is returned, with catalog_budget_exhausted reported. Nearby cities and districts can be included. This is one search call, including provider lookups.
Hotel filters apply before pricing. The service covers up to 1,000 matching hotels. If that cap is reached, inspect data.coverage.service_limit_reached, complete and ranking_scope; do not call the result an exhaustive destination search.
page_size controls the returned page, not how many matching hotels are priced. Each result contains a hotel summary and rates.provider_results[], with one lowest eligible returned offer per provider.
Result order
For nearest or closest first, send sort: "distance_asc". It sorts priced hotels by exact distance from the destination center, with unpriced hotels last. geographic_scope.radius_km is the search area; each hotel’s distance_meters is its own distance.
The default sort: "distance_brek_savings_desc" uses 0–5, 5–10, 10–15 and 15–20 km bands from the resolved destination center. Within each band, hotels sort by the greatest Brek price advantage: the cheapest other provider total minus the Brek total, using comparable full-stay quotes including mandatory taxes and fees in the same display currency. This is an absolute amount, not a percentage. Positive means Brek is cheaper; zero means equal; negative means another provider is cheaper. A missing or ineligible Brek/competitor quote gives no comparison and sorts last within that band. Ties use lowest stay total, then distance and hotel ID. The signed amount and compared provider appear in brek_price_advantage. Use distance_price_asc for lowest total within each distance band. A hotel exactly on a boundary belongs to the nearer band. Hotels without a comparable quote are last; unknown distances never count as zero. Sorting covers the complete priced candidate set before pagination. distance_meters, distance_bucket and data.ranking explain the order. Use sort: "stay_total_asc" for price ascending across the entire area. If a destination center is unavailable, the response explicitly reports a price-sort fallback.
These are straight-line distances from the resolved city center or supplied coordinates, not walking or driving distances. API distances remain in meters and search radii in kilometers. The Claude / ChatGPT UI displays US hotel distances in miles and other destinations in kilometers; internal 5 km bands stay unchanged. Consumer search cards include up to eight available hotel photos with previous/next controls, without a new API call. In the Claude / ChatGPT UI, provider rows inside each hotel sort by lowest total. Raw API provider_results arrays have no price-order guarantee; use lowest_provider or sort eligible stay_total amounts. Other orders are distance_asc (straight-line distance), stay_total_desc (highest whole-stay price first) and review_score_desc (displayed guest score, then review count). Unpriced hotels remain last in every order.
Filters & sorting: complete field reference
Request fields
| Field | Required | Type | Details |
|---|---|---|---|
location | Required | object | Two-letter country plus city or latitude/longitude; region optional |
hotel_filters | Optional | object | See request and field notes below |
context | Required | object | Stay dates, occupancy, currency and residency |
rate_filters | Optional | object | See request and field notes below |
providers | Optional | array | See request and field notes below |
page_size | Optional | integer | 1–200 |
billing | Optional | object | Maximum new units authorized for this call |
sort | Optional | string | See request and field notes below |
hotel_filters
| Field | Type | Meaning |
|---|---|---|
amenities | array | All requested amenities must match. Broad wifi, parking, pool and fitness include feed variants. pet_friendly / pet-friendly accepts pet-allowed themes; free-wifi means wifi::free. |
star_rating_min | number | Minimum hotel star classification, distinct from guest reviews. |
star_rating_max | number | Maximum hotel star classification, 0–5. |
star_ratings | array | Accepted exact star classifications; intersects with any min/max range. |
review_score_min | number | Minimum guest score normalized to 10, using the displayed review_summary provider. Unknown scores/scales do not qualify. |
review_count_min | integer | Minimum review count from that same review_summary provider. Counts are not added across providers. |
property_type | string | One exact source property type; use instead of property_types. |
property_types | array | Accept any of these source property types. Use instead of property_type. |
name_contains | string | Case-insensitive text in the hotel name; treated as literal text, not a regular expression. |
max_distance_km | number | Maximum straight-line distance from the resolved destination center, up to 20 km. Requires a city/destination or latitude/longitude. |
rate_filters
| Field | Type | Meaning |
|---|---|---|
refundable_only | boolean | Require known refundable terms; unknown terms do not qualify. |
breakfast_included | boolean | Require an offer explicitly marked breakfast included. |
stay_total_min | number | Minimum full-stay amount in context.currency for all requested rooms, including mandatory taxes and fees. Not a nightly price. |
stay_total_max | number | Maximum full-stay amount in context.currency for all requested rooms, including mandatory taxes and fees. Applies to each returned offer before minima. |
context requires either explicit hotel-local check_in and check_out, or date_intent: "tonight" without explicit dates, plus rooms (1–8), each with adults (1–8) and children_ages (ages 0–17). Stays are 1–60 calendar nights. Same-day check-in is allowed using the destination or hotel local date, even when UTC is already tomorrow. The server resolves an IANA time zone from destination coordinates or hotel metadata before rejecting past dates. Traveler context.time_zone never overrides the property calendar. date_intent: "tonight" resolves one local night on the server; use the returned explicit dates in follow-ups. data.date_context reports the time zone, local date and resolution timestamp. currency defaults to USD and market.residency_country to US over HTTP; MCP can fill omitted preferences from client metadata (see the MCP guide); set both explicitly for your traveler.
rate_filters supports refundable_only, breakfast_included, stay_total_min and stay_total_max. Budgets are whole-stay totals for all requested rooms in the requested currency, including mandatory fees. Complete filter guide. It filters returned offers before choosing provider/hotel minima, and cannot recover plans omitted by supplier caps. Hotels and provider rows without a qualifying offer have no comparable quote; unknown refundability never passes refundable_only. providers restricts providers; enabled status is available at capabilities.
hotel_filters supports facilities, star ranges or exact stars, guest-score/review-count thresholds, property types, hotel name and maximum distance. All fields, limits and examples. All requested amenities must match. Broad wifi, parking, pool and fitness include their specific feed variants. free-wifi means wifi::free; pet_friendly / pet-friendly accepts pet-allowed themes. pets::allowed requires that exact source tag. Star minimum cannot exceed maximum. Metadata filters reflect source records and are not a guarantee of each hotel policy.
Request example
The captured request uses 2026-11-12 to 2026-11-14, 2 adults, 1 room, USD. Replace dates with your own future dates for a new rate call. Use a fresh Idempotency-Key per intended operation; keep it for retries.
curl 'https://www.hoteluse.dev/v1/hotels/search' \
-H "Authorization: Bearer $HOTELUSE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: replace-with-a-unique-operation-id' \
--data '{
"location": {
"country": "US",
"city": "Bellevue",
"region": "WA"
},
"hotel_filters": {
"name_contains": "Hilton Bellevue"
},
"context": {
"check_in": "2026-11-12",
"check_out": "2026-11-14",
"rooms": [
{
"adults": 2,
"children_ages": []
}
],
"currency": "USD",
"market": {
"residency_country": "US"
}
},
"page_size": 25
}'Captured response
Captured 2026-10-21 17:50:47 UTC. The preview below is abridged for reading: arrays and static records can be shortened or selected. The downloadable JSON preserves the full captured transport page. Only request/session/billing identifiers and cursors are redacted. Historical sessions cannot be resumed.
{
"schema_version": "1.0",
"request_id": "req_documentation_capture",
"data": {
"context": {
"check_in": "2026-11-12",
"check_out": "2026-11-14",
"rooms": [
{
"adults": 2,
"children_ages": []
}
],
"currency": "USD",
"market": {
"residency_country": "US"
}
},
"quote_session_id": "qs_documentation_capture_expired",
"provider_results": [
{
"provider": "expedia",
"status": "complete",
"upstream_requests": 1,
"completed_requests": 1,
"failed_requests": 0
},
{
"provider": "booking",
"status": "complete",
"upstream_requests": 1,
"completed_requests": 1,
"failed_requests": 0
},
{
"provider": "agoda",
"status": "complete",
"upstream_requests": 1,
"completed_requests": 1,
"failed_requests": 0
},
{
"provider": "brek",
"status": "complete",
"upstream_requests": 3,
"completed_requests": 3,
"failed_requests": 0
}
],
"upstream_requests": 6,
"coverage": {
"matching_hotels": 1,
"matching_hotels_is_lower_bound": false,
"priced_hotels": 1,
"available_hotels": 1,
"unmapped_hotels": 0,
"complete": true,
"service_limit_reached": false,
"ranking_scope": "matching_hotels"
},
"search_session_id": "qs_documentation_capture_expired",
"geographic_scope": {
"source": "Auto Suggest",
"provider": "google",
"center": {
"latitude": 47.6101497,
"longitude": -122.2015159
},
"radius_km": 20,
"address_city": "Bellevue",
"country": "US"
},
"results": [
{
"hotel": {
"hotel_id": "hu_69450c903d9c06226f1ce17b",
"name": "Hilton Bellevue",
"city": "Bellevue (WA)",
"country": "US",
"star_rating": 4,
"geo": {
"longitude": -122.18915,
"latitude": 47.60723
},
"property_type": "hotel"
},
"rates": {
"hotel_id": "hu_69450c903d9c06226f1ce17b",
"status": "complete",
"lowest_provider": "brek",
"provider_results": [
{
"provider": "expedia",
"status": "ok",
"lowest_offer": {
"offer_id": "offer_396036e4df6c526dc296a81ff817",
"provider": "expedia",
"hotel_id": "hu_69450c903d9c06226f1ce17b",
"shared_room_group_id": null,
"currency": "USD",
"room_name": "Room, 1 King Bed with Sofa bed, Balcony - No-Refunds",
"external_room_id": "192500",
"meal_plan": "room_only",
"cancellation": {
"refundable": false,
"free_cancellation_until": null,
"summary": "This reservation is non-refundable and cannot be cancelled or changed.Stay extensions require a new reservation.",
"penalties": [
{
"deadline": "2026-10-21T17:50:45.000Z",
"type": "percent",
"value": "100",
"currency": null
}
]
},
"stay_total": {
"amount": "489.44",
"currency": "USD"
},
"price": {
"base": "423.10",
"taxes_and_fees": "66.34",
"pay_at_property": "0.00",
"stay_total": "489.44",
"currency": "USD"
},
"taxes_and_mandatory_fees_included": true,
"checked_at": "2026-10-21T17:50:45.160Z"
}
},
{
"provider": "booking",
"status": "ok",
"lowest_offer": {
"offer_id": "offer_55fdb1d090cafbad490177f281c9",
"provider": "booking",
"hotel_id": "hu_69450c903d9c06226f1ce17b",
"shared_room_group_id": null,
"currency": "USD",
"room_name": "Room 18067302",
"external_room_id": "18067302",
"meal_plan": "no_plan",
"cancellation": {
"refundable": false,
"free_cancellation_until": null,
"summary": null,
"penalties": []
},
"conditional_charges": [],
"price_scope": "requested_room",
"stay_total": {
"amount": "489.45",
"currency": "USD"
},
"price": {
"base": "423.10",
"taxes_and_fees": "66.35",
"pay_at_property": null,
"stay_total": "489.45",
"currency": "USD"
},
"taxes_and_mandatory_fees_included": true,
"checked_at": "2026-10-21T17:50:45.239Z"
}
},
{
"provider": "agoda",
"status": "ok",
"lowest_offer": {
"offer_id": "offer_e13afa920e1d7dcebc6f9af63e4d",
"provider": "agoda",
"hotel_id": "hu_69450c903d9c06226f1ce17b",
"shared_room_group_id": null,
"currency": "USD",
"room_name": "1 KING BED with SOFA SLEEPER",
"external_room_id": "3530703",
"meal_plan": "room_only",
"cancellation": {
"refundable": false,
"free_cancellation_until": null,
"summary": "This booking is Non-Refundable and cannot be amended or modified. Failure to arrive at your hotel or property will be treated as a No-Show and will incur a charge of 100% of the booking value (Hotel policy).",
"penalties": [
{
"deadline": null,
"deadline_local": "2026-10-21T00:00:00",
"until": null,
"until_local": null,
"type": "amount",
"value": 489.45,
"currency": "USD",
"time_basis": "hotel_local"
}
],
"free_cancellation_until_local": null,
"time_basis": "hotel_local",
"timezone": "America/Los_Angeles",
"provider_policy": {
"code": "365D100P_100P",
"parameters": [
{
"days": 365,
"charge": "P",
"value": 100
}
]
}
},
"room_type_guaranteed": true,
"stay_total": {
"amount": "489.45",
"currency": "USD"
},
"price": {
"base": "423.10",
"taxes_and_fees": "66.35",
"pay_at_property": "0.00",
"stay_total": "489.45",
"currency": "USD"
},
"taxes_and_mandatory_fees_included": true,
"checked_at": "2026-10-21T17:50:45.310Z"
}
},
{
"provider": "brek",
"status": "ok",
"lowest_offer": {
"offer_id": "offer_e2c92fbd284a6b1746df16ec5b42",
"provider": "brek",
"hotel_id": "hu_69450c903d9c06226f1ce17b",
"shared_room_group_id": null,
"currency": "USD",
"room_name": "ROOM, KING BED, SOFA",
"external_room_id": "1252232395",
"room_components": [
{
"room_id": "1252232395",
"name": "ROOM, KING BED, SOFA",
"occupancy_reference": 1
}
],
"meal_plan": null,
"supplier_board_code": "0",
"cancellation": {
"refundable": false,
"free_cancellation_until": null,
"summary": null,
"penalties": [
{
"deadline": "2026-10-19T05:00:00.000Z",
"type": "IMPORT",
"value": 241.0681,
"currency": "USD"
}
]
},
"inventory_source": "118",
"price_breakdown": {
"inventory_total": "241.07",
"inventory_room_total": "207.54",
"included_taxes_and_fees": "33.52",
"markup_basis": "inventory_room_total",
"rounding": "per_night",
"rounding_adjustment": "-0.01",
"markup_rate": "0.07",
"markup_amount": "14.52",
"pay_at_property": "0.00"
},
"stay_total": {
"amount": "255.58",
"currency": "USD"
},
"price": {
"base": "222.06",
"taxes_and_fees": "33.52",
"pay_at_property": "0.00",
"stay_total": "255.58",
"currency": "USD"
},
"taxes_and_mandatory_fees_included": true,
"checked_at": "2026-10-21T17:50:45.638Z"
}
}
]
}
}
],
"next_cursor": null,
"reuse_until": "2026-10-21T18:00:45.995Z"
},
"usage": {
"hotel_record_units": 0,
"search_calls": 1,
"room_calls": 0,
"trial_units_used": 1,
"paid_units": 0,
"paid_usd": "0.000",
"unit_price_usd": "0.040",
"billing_receipt_id": "bill_documentation_capture",
"replayed": false
}
}| Field | Meaning |
|---|---|
schema_version | Current response schema, 1.0. |
request_id | Include this value when reporting an issue. |
data.provider_results | Provider execution status, completed/failed request counts, and errors. |
data.next_cursor | Non-null means another page is available. A small page does not mean complete coverage. |
usage | Actual units, signup units used, paid units and USD charged for this response. |
Booking links
Available Expedia, Booking and Agoda offers include an optional booking_url with HotelUse affiliate tracking by default, for both HTTP and developer MCP. Room-group provider minima include the matching lowest offer’s link. Supplier dates, occupancy, device and room/rate parameters are preserved. Links are omitted when no safe supplier URL is available. A booking may earn HotelUse a commission; booking and payment happen at the provider. Links do not change API usage billing.
Search by latitude / longitude
Supply location.country plus numeric location.latitude (−90 to 90) and location.longitude (−180 to 180). Both coordinates are required together; zero is valid. Coordinates take precedence over city/region and bypass the place lookup. The country code filters hotel records; coordinates do not infer or verify a country.
{
"location": {"country": "US", "latitude": 47.6101, "longitude": -122.2015},
"hotel_filters": {"max_distance_km": 5}
}For live search, also supply context with dates and rooms. Without an explicit radius, destination search can expand from 20 to 40/60 km when sparse. max_distance_km fixes the radius at more than 0 and at most 20 km, disabling expansion. Follow-up pages keep the exact location and filters. The response reports geographic_scope.source: "coordinates", its center, radius and hotel-local time zone.
Search metadata freshness
For indexed destinations, geographic_scope.catalog_index reports the candidate snapshot time. Regional search metadata refreshes every 15 minutes and is not used after 30 minutes without a successful refresh. The complete indexed area covers the requested search circle. Full hotel records come from the source catalog, with current filters rechecked. New or reclassified candidates can appear after the next refresh. Prices are queried live.
Pagination
For the next page, POST to this same endpoint with only the returned quote_session_id and cursor. Quote-session pages are account-bound, use no additional search or room units, and expire after 10 minutes. They reuse the original prices.
{
"quote_session_id": "qs_from_your_live_response",
"cursor": "cursor_from_your_live_response"
}