Source: https://www.hoteluse.dev/docs/ # HotelUse documentation Give your agent hotel search, provider price comparisons, room rates and hotel information. Use the HTTP API or MCP. [Start with the Quickstart](/docs/quickstart.html) · [Get an API key](https://www.hoteluse.dev/#dashboard) · [Explore live requests](/#developers) ## Your hotel workflow Start with `search_hotels` for a destination and itinerary. Use a returned HotelUse ID with `get_hotel` for hotel information, or `get_room_rates` for room options and terms. ## Three tools, one account | Tool | HTTP endpoint | What it returns | | --- | --- | --- | | [search_hotels](/docs/api/search-hotels.html) | `POST /v1/hotels/search` | Search hotels | | [get_hotel](/docs/api/get-hotel.html) | `POST /v1/hotels/get` | Get hotel information | | [get_room_rates](/docs/api/get-room-rates.html) | `POST /v1/rates/rooms` | Get room rates | ## Real production examples Every reference page includes a response captured from https://www.hoteluse.dev. This capture uses Hilton Bellevue, 2026-11-12 to 2026-11-14, 2 adults, 1 room, USD. Collected 2026-10-21 17:50:47 UTC. | Provider | Lowest stay total | | --- | --- | | expedia | $489.44 USD | | booking | $489.45 USD | | agoda | $489.45 USD | | brek | $255.58 USD | The room endpoint returned 242 offers across four providers, including 4 Booking room IDs and 56 Booking rate products. [See the actual room offers](/docs/api/get-room-rates.html). Captured prices are historical; run a new request for current availability. ## Filters and result order [Filters & sorting](/docs/filters.html): star classification, guest-review score and count, facilities, property types, distance, full-stay budgets, cancellation and breakfast. The same filters work through HTTP and MCP. ## Built for agents [Documentation index](/llms.txt) · [Full Markdown corpus](/llms-full.txt) · [OpenAPI 3.1](/docs/openapi.json) · [Agent quickstart](/agent.md) Docs and examples require no login. Developer API calls require an account and API key. The [consumer search connector](/docs/mcp.html#consumer-search-connector) works without either. Accounts start with 50 destination search calls, 50 room calls and 1,000 hotel information units, issued once. [Billing and limits](/docs/pricing-and-limits.html). --- Source: https://www.hoteluse.dev/docs/quickstart.html # Quickstart From account to first API response. No subscription or card is required to use signup credits. ## 1. Sign in Open the [HotelUse dashboard](https://www.hoteluse.dev/#dashboard), choose Sign in, then Continue with Google or email. First-time sign-in creates your account. Complete the Google or email verification in the browser when requested. ## 2. Create an API key In Dashboard → API keys, enter a key name and choose Create API key. Save the displayed secret once; it cannot be retrieved later. Store it in your application's secret manager or environment. ```bash export HOTELUSE_API_KEY="hu_live_replace_with_your_key" ``` Do not commit the key or put it in browser JavaScript. API keys are for trusted server code. See [authentication](/docs/authentication.html) for rotation and revocation. ## 3. Make your first call This static lookup does not need dates. It uses at most one hotel record unit. A repeat of the same record version is free. ```bash curl 'https://www.hoteluse.dev/v1/hotels/get' \ -H "Authorization: Bearer $HOTELUSE_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: replace-with-a-unique-operation-id' \ --data '{ "hotel_id": "hu_69450c903d9c06226f1ce17b", "billing": { "max_units": 1 } }' ``` A successful result includes `data.hotel.name: "Hilton Bellevue"`, provider mappings, a record version and a usage receipt. [Full captured response](/docs/examples/get_hotel.json). ## 4. Search live prices Use your own future check-in and check-out dates. Here is a JavaScript example with dates calculated from today. Run in Node.js 22 or later. ```javascript import { randomUUID } from 'node:crypto'; const date = offset => { const d = new Date(); d.setUTCDate(d.getUTCDate() + offset); return d.toISOString().slice(0, 10); }; const response = await fetch('https://www.hoteluse.dev/v1/hotels/search', { method: 'POST', headers: { Authorization: 'Bearer ' + process.env.HOTELUSE_API_KEY, 'Content-Type': 'application/json', 'Idempotency-Key': randomUUID() }, body: JSON.stringify({ location: { country: 'US', city: 'Bellevue', region: 'WA' }, context: { check_in: date(14), check_out: date(16), rooms: [{ adults: 2, children_ages: [] }], currency: 'USD', market: { residency_country: 'US' } }, page_size: 25 }) }); const result = await response.json(); if (!response.ok) throw new Error(JSON.stringify(result.error)); console.log(result.data.results, result.data.coverage, result.usage); ``` [Destination search reference](/docs/api/search-hotels.html) · [Room rates reference](/docs/api/get-room-rates.html). Search uses one search call; opening room rates uses one room call. ## Python This example uses only Python's standard library. Set `HOTELUSE_API_KEY` in the environment first. ```python import json, os, uuid, urllib.request request = urllib.request.Request( 'https://www.hoteluse.dev/v1/hotels/get', data=json.dumps({'hotel_id': 'hu_69450c903d9c06226f1ce17b', 'billing': {'max_units': 1}}).encode(), headers={ 'Authorization': 'Bearer ' + os.environ['HOTELUSE_API_KEY'], 'Content-Type': 'application/json', 'Idempotency-Key': str(uuid.uuid4()), }, method='POST', ) with urllib.request.urlopen(request, timeout=35) as response: result = json.load(response) print(result['data']['hotel']['name'], result['usage']) ``` ## Next steps [Connect through MCP](/docs/mcp.html) · [Handle errors and retries](/docs/errors-and-retries.html). --- Source: https://www.hoteluse.dev/docs/authentication.html # Authentication & API keys ## Account access Use Google or an emailed six-digit code on the [dashboard](https://www.hoteluse.dev/#dashboard). Sign-in creates an account if needed. No phone number is required. Login uses a browser session; hotel API calls use an API key. ## Server authentication ```http Authorization: Bearer hu_live_YOUR_API_KEY Content-Type: application/json ``` Use HTTPS and the base URL `https://www.hoteluse.dev`. Both HTTP and MCP use the same account keys and balance. A missing, invalid or revoked key returns HTTP 401. ## Key lifecycle Create a key in Dashboard → API keys. The full value is shown once and stored as a hash server-side. Label keys by application. Rotate by creating a replacement, updating your application and revoking the old key. Revocation takes effect for subsequent requests. Keys on the same account share signup credits, prepaid balance, data access caps and rate limits. Creating another key does not create another free allowance. ## Agent onboarding An agent can read these docs without authentication, open the dashboard, guide sign-in, and help configure the key. The account owner completes any identity verification and decides where the key is stored. Never ask someone to paste a key into an issue, support email or a public prompt. [Quickstart](/docs/quickstart.html) · [Copy an agent setup prompt](/agent.md). --- Source: https://www.hoteluse.dev/docs/filters.html # Filters & sorting Combine hotel conditions with live rate conditions. Hotel conditions apply before supplier pricing and before the 1,000-candidate search cap. Rate conditions apply to returned offers before minimum prices and room groups are selected. All supplied conditions must hold; arrays of star ratings or property types accept any listed value. All requested amenities are required. ## Where filters work | Operation | hotel_filters | rate_filters | Other controls | | --- | --- | --- | --- | | search_hotels | Yes | Yes | providers, sort, page_size | | get_room_rates | No; one identified hotel | Yes | providers, page_size | | get_hotel | No; one identified hotel | No live prices | hotel_id | Developer HTTP and developer MCP use the same nested request. Consumer MCP search uses flat destination/dates/occupancy arguments, with the same hotel_filters and rate_filters objects. Every filter is optional. Unsupported fields and invalid ranges return 400; no credits are charged. Changing filters starts a new quote call. ## 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. | HotelUse uses Expedia’s star classification when one unambiguous Expedia mapping is available; other properties retain the catalog classification. `star_classification` identifies the source, verification status and check time. Missing or ambiguous mapped classifications stay unknown. Classification facts refresh within seven days, independently of live prices. HotelUse does not overwrite B2B source records. Provider classifications can differ. Star classification and guest-review score are different. A four-star hotel does not imply a guest score of 8/10. star_ratings accepts 1–5 distinct whole-star values; min/max ranges use 0–5 and intersect with an exact list. property_types accepts 1–12 distinct source values, such as hotel or resort; use either property_type or property_types. Amenities accepts up to 20 canonical source codes. Unknown source metadata does not establish that a condition is satisfied. ## Guest-review rules review_score_min is a 0–10 threshold against review_summary.score_out_of_10. The displayed review_summary selects the provider with the largest valid review count among records with a usable score and known scale. Source order breaks count ties. A 4.5/5 source score becomes 9/10; an ambiguous 4.5 with no scale does not qualify. Scores above 5 and at most 10 use a 10-point scale when no explicit scale exists. Invalid explicit scales stay unknown. Star ratings are never substituted. review_count_min applies to that same provider. Counts are not added across Booking, Expedia, Agoda or other sources. A high score from a small provider sample cannot bypass the lower score displayed from the selected larger sample. Missing review summaries are excluded whenever a review condition is requested. These are source catalog facts, not independent certification of review quality or hotel star classification. ## Live 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. | Budget amounts are in context.currency (flat currency on consumer MCP). They include every requested night and every requested room, plus mandatory taxes and fees. They are not nightly or per-room budgets. Bounds are inclusive, from 0 to 100,000,000; minimum cannot exceed maximum. A 2-night, 2-room stay_total_max of 600 means a combined stay total of at most 600, not 600 per room or per night. Expedia, Booking and Agoda return native quotes in the requested currency. Brek settles in USD and uses a fresh FX snapshot for other display currencies and mandatory local-currency fees. Inspect currency_conversion and mandatory_fees; converted totals are estimates and include the listed local fees once. Offers with unconfirmed mandatory fees do not qualify for budget filters. Refundability must be explicitly true to pass refundable_only. Unknown terms do not qualify. Breakfast must be explicitly included to pass breakfast_included. These filters choose among the plans suppliers actually return; they cannot retrieve plans omitted by supplier response caps. A provider can have no matching offer while the hotel still has other available rooms. Search provider status no_matching_offer means filters removed otherwise returned confirmed-fee offers; no_availability means no offer was returned. Incomplete prices and failed calls retain their own statuses. Detailed room calls contain only matching offers and groups; provider_results still records the underlying call outcome. ## Distance and result order City destinations resolve through Auto Suggest. Explicit latitude/longitude uses the supplied center without Auto Suggest. Destination search starts at 20 km and expands to 40 km then 60 km only below 50 static candidates. An explicit max_distance_km disables expansion and can narrow the area to more than 0 and at most 20 km. It requires a city/destination or latitude/longitude pair and measures straight-line distance from its center, not route distance. It does not mutate the shared destination cache. The default distance_brek_savings_desc sorts priced hotels into 0–5, 5–10, 10–15 and 15–20 km bands, then by greatest Brek price advantage inside each band: cheapest other eligible provider total minus Brek total, in the display currency. A positive amount is a saving; a negative amount means a competitor is cheaper. Missing comparisons go last within the band. Price, distance and hotel ID break ties. Exact boundaries belong to the nearer band. distance_price_asc retains price ascending within bands. stay_total_asc sorts all matched hotels globally by price. Unpriced hotels remain last. Claude and ChatGPT display provider rows in price order. Raw API provider arrays do not guarantee price order; use lowest_provider or sort eligible returned totals in your code. data.ranking, distance_meters and distance_bucket explain the order. ## Duplicate catalog identities Live destination searches consolidate records only when GIATA and exact provider IDs establish one property, or when the entire namespaced provider-ID set is identical. Both paths also require matching full names, country, nearby coordinates and non-conflicting GIATA IDs. Names or addresses alone are insufficient. Distinct GIATA properties, including separate club-level or residence listings, stay separate. Inactive GIATA provider IDs are never transferred into a canonical quote mapping. Hotel information retains source timestamps and hotel record versions. Room results use the same hotel identity returned by search. HotelUse consolidates verified aliases when comparing provider quotes; preserve the exact returned hotel_id for follow-up questions. catalog_quality reports duplicate_records_collapsed, inactive_duplicate_mappings_ignored and identity_verification. Verification reads the existing GIATA catalog within a bounded sub-second budget and caches successful facts for up to five minutes. Missing, contradictory or unavailable identity evidence leaves the records separate and preserves valid supplier shopping. No B2B inventory or supplier mapping is rewritten. A known inactive Booking mapping may be restored only in the HotelUse live overlay when Booking’s current details API confirms the same provider ID, hotel name, country and coordinates. Verification and room-name/photo caches are stored separately in HotelUse and expire after one day. A differently named sub-property is never substituted. ## Facility names, property aliases and coverage Broad facility requests include canonical variants: kitchen includes kitchenette/shared kitchens, hot-tub includes recorded spa/jacuzzi variants, and family-friendly, kids-friendly, accessibility and laundry use their recorded subtypes. TV excludes security cameras. free-wifi remains restricted to wifi::free. Static free-breakfast is a property facility; rate_filters.breakfast_included requires the actual quoted rate to include breakfast. Use rate_filters.refundable_only for cancellation terms, not a static facility code. Pet-friendly filtering excludes explicit pet bans; service-animal access alone does not imply pet access. Property aliases such as condo, guesthouse, farm-house, campground, rv, mobile-home and house-boat map to source feed spellings. Raw records retain original property_type and facility codes. A returned lowest_offer is an actual supplier quote with its reported fee status. coverage_incomplete means other branches or options could not be checked; it does not invalidate that returned quote. rates.availability_status distinguishes available, no_matching_offer, no_availability and unknown. Unmapped, unsupported and failed lookups are not evidence of a sold-out hotel. Supplier date restrictions (unsupported_dates) and occupancy restrictions (unsupported_occupancy) are permanent for the submitted request and are not retried. Other providers can still quote the same hotel and stay. ## HTTP and developer MCP example This is a combined request shape, not a promised result count. Replace the dates with future dates for your trip. Restrictive combinations can return no matching rates. All three endpoint pages also link to this filter guide. ```json { "location": { "country": "US", "city": "Bellevue", "region": "WA" }, "context": { "check_in": "2026-11-12", "check_out": "2026-11-14", "rooms": [ { "adults": 2, "children_ages": [] } ], "currency": "USD", "market": { "residency_country": "US" } }, "hotel_filters": { "star_ratings": [ 4, 5 ], "review_score_min": 8, "review_count_min": 100, "amenities": [ "wifi", "pool" ], "property_types": [ "hotel", "resort" ], "max_distance_km": 5 }, "rate_filters": { "stay_total_max": 600, "refundable_only": true, "breakfast_included": true }, "sort": "distance_brek_savings_desc", "page_size": 25 } ``` POST this body to /v1/hotels/search or pass it as arguments to the developer MCP search_hotels tool. ## Consumer MCP example ```json { "name": "search_hotels", "arguments": { "destination": "Bellevue, Washington", "country": "US", "check_in": "2026-11-12", "check_out": "2026-11-14", "rooms": [ { "adults": 2, "children_ages": [] } ], "currency": "USD", "hotel_filters": { "star_ratings": [ 4, 5 ], "review_score_min": 8, "review_count_min": 100, "amenities": [ "wifi", "pool" ], "property_types": [ "hotel", "resort" ], "max_distance_km": 5 }, "rate_filters": { "stay_total_max": 600, "refundable_only": true, "breakfast_included": true }, "sort": "distance_brek_savings_desc" } } ``` For a room follow-up, copy the hotel_id, original dates/rooms/currency and search_session_id as search_quote_session_id. The search reference inherits omitted dates, rooms, currency, language, residency, providers and rate_filters. Explicit arguments override inherited values except device; send rate_filters: {} to clear inherited rate constraints. Hotel filters describe the search candidate set and are not room-tool arguments. ## Pagination and coverage Search ranking is computed across the returned candidate set before pagination. Copy the exact quote_session_id and next_cursor into a page-only request; do not calculate a cursor or mix destination/filters into it. Pages reuse the original filtered quote. A search can still reach the 1,000-candidate cap; check coverage before describing it as exhaustive. page_size controls output pages, not candidate pricing. [Search API reference](/docs/api/search-hotels.html) · [Room API reference](/docs/api/get-room-rates.html) · [OpenAPI](/docs/openapi.json). --- Source: https://www.hoteluse.dev/docs/api/search-hotels.html # 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](/?tool=search_hotels#developers) · [Download full captured response](/docs/examples/search_hotels.json) ## 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](/docs/filters.html) ## 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](/docs/filters.html). 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](/v1/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](/docs/filters.html). 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. ```bash 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. ```json { "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. ```json { "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. ```json { "quote_session_id": "qs_from_your_live_response", "cursor": "cursor_from_your_live_response" } ``` [Pricing and limits](/docs/pricing-and-limits.html) · [Errors and retries](/docs/errors-and-retries.html). --- Source: https://www.hoteluse.dev/docs/api/get-hotel.html # Get hotel information `POST /v1/hotels/get` · MCP tool: `get_hotel` Get information about one hotel by HotelUse ID: address, photos, facilities, policies and source metadata. No live rates. Each newly read hotel version costs $0.005 after signup credits; repeat reads of the same version are free. [Run this tool on HotelUse](/?tool=get_hotel#developers) · [Download full captured response](/docs/examples/get_hotel.json) ## Information for one hotel Pass a HotelUse `hu_…` ID returned by `search_hotels`. The response contains `data.hotel` with address, photos, facilities, descriptions, policies and source metadata. No stay dates or live price request are needed. Use the same ID with `get_room_rates` to explore room options. Each newly read hotel version uses one hotel information unit. Repeat reads of the same version are free. [Filters & sorting: complete field reference](/docs/filters.html) ## Request fields | Field | Required | Type | Details | | --- | --- | --- | --- | | `hotel_id` | Required | string | See request and field notes below | | `billing` | Optional | object | Maximum new units authorized for this call | | `include` | Optional | array | See request and field notes below | ## Request example This static request does not require stay dates or occupancy. Use a fresh Idempotency-Key per intended operation; keep it for retries. ```bash curl 'https://www.hoteluse.dev/v1/hotels/get' \ -H "Authorization: Bearer $HOTELUSE_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: replace-with-a-unique-operation-id' \ --data '{ "hotel_id": "hu_69450c903d9c06226f1ce17b", "billing": { "max_units": 1 } }' ``` ## 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. ```json { "schema_version": "1.0", "request_id": "req_documentation_capture", "data": { "hotel": { "hotel_id": "hu_69450c903d9c06226f1ce17b", "name": "Hilton Bellevue", "address": { "address": "300 112th Ave SE", "city": "Bellevue (WA)", "state": "Washington", "country": "US", "postalCode": "98004" }, "giata_id": "65307", "geo": { "longitude": -122.18915, "latitude": 47.60723 }, "star_rating": 4, "timezone": "America/Los_Angeles", "provider_records": [ { "connection": "tgx", "provider": "abreu", "external_hotel_id": "2529194" }, { "connection": "tgx", "provider": "hotelbeds", "external_hotel_id": "131339" }, { "connection": "tgx", "provider": "w2m", "external_hotel_id": "JP047245" }, { "connection": "tgx", "provider": "hprotravel", "external_hotel_id": "11069c" }, { "connection": "tgx", "provider": "tbo", "external_hotel_id": "1096022" }, { "connection": "tgx", "provider": "priceline", "external_hotel_id": "59c1c29f-77ac-5db1-ae08-67d7b6639582" }, { "connection": "tgx", "provider": "expedia_eps", "external_hotel_id": "4497" }, { "connection": "metasearch", "provider": "agoda", "external_hotel_id": "166523" }, { "connection": "metasearch", "provider": "expedia", "external_hotel_id": "4497" }, { "connection": "metasearch", "provider": "hotels.com", "external_hotel_id": "4497" }, { "connection": "tgx", "provider": "rakuten", "external_hotel_id": "3H9L" }, { "connection": "tgx", "provider": "restel", "external_hotel_id": "809596" }, { "connection": "tgx", "provider": "price_travel", "external_hotel_id": "120318" }, { "connection": "tgx", "provider": "goglobal", "external_hotel_id": "143194" }, { "connection": "tgx", "provider": "webbeds", "external_hotel_id": "146946" }, { "connection": "tgx", "provider": "ratehawk", "external_hotel_id": "7441551" }, { "connection": "metasearch", "provider": "booking.com", "external_hotel_id": "180673" } ], "source_updated_at": "2026-10-06T11:08:12.169Z", "record_version": "2026-10-06T21:43:17.002Z" } }, "usage": { "hotel_record_units": 0, "search_calls": 0, "room_calls": 0, "trial_units_used": 0, "paid_units": 0, "paid_usd": "0.000", "unit_price_usd": "0.005", "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.hotel` | One static hotel record with provider ID mappings, source timestamps and a record version. | | `usage` | Actual units, signup units used, paid units and USD charged for this response. | ## Hotel record fields `include` accepts `provider_records` and `provenance`. The current response already includes the full public record; these flags do not expose private supplier fields. | Field | Meaning | | --- | --- | | `hotel_id` | Stable HotelUse identifier for subsequent rate calls. | | `giata_id` | GIATA identity where present, otherwise null. | | `provider_records[]` | Connection, provider and external_hotel_id; no supplier credentials. | | `source_updated_at` | Reported source refresh timestamp, or null if unavailable. | | `record_version` | Version used for repeat-read billing. | | `address`, `geo`, `star_rating`, `amenities`, `images`, `descriptions`, `timezone` | Normalized static data. Source values can be missing or null. | ## Pagination This operation returns one record and has no result pages. [Pricing and limits](/docs/pricing-and-limits.html) · [Errors and retries](/docs/errors-and-retries.html). --- Source: https://www.hoteluse.dev/docs/api/get-room-rates.html # Get room rates `POST /v1/rates/rooms` · MCP tool: `get_room_rates` Read available supplier-specific room offers, terms, and stay totals for one hotel and itinerary. One room call ($0.06 after signup credits). Room equivalence across providers is not assumed. More pages of the same quote session are free. [Run this tool on HotelUse](/?tool=get_room_rates#developers) · [Download full captured response](/docs/examples/get_room_rates.json) ## Rooms and rate plans Pass one HotelUse ID and an itinerary. Multi-room searches preserve each room’s adult count and child ages. Expedia, Booking, Agoda and Brek support multi-room search and room quotes. Booking detailed quotes and Agoda quotes validate each distinct room allocation, shared provider room inventory and the full-party total. They combine the same provider room type across rooms, then use GIATA to group equivalent types across providers. Agoda also confirms the amount against its native whole-party quote. Original child ages are preserved. Unknown stock or failed occupancy branches produce partial coverage, never a single-room price labeled as a full-party total. Combined offers expose `room_allocations[]` with each room’s guests, full-stay price and cancellation terms; aggregate cancellation amounts must not be inferred from one room. Unsupported room setups are reported explicitly, never as sold out. HotelUse performs GIATA room-type mapping on the server, using the hotel GIATA ID and unique provider room descriptions. The response includes grouped `data.room_groups[]` and the original `data.offers[]` across providers. Different rate plans for one room remain separate offers: breakfast, payment timing, occupancy and cancellation can differ. Use `room_groups[].provider_prices[]` for each provider's lowest returned rate in that room family; `offer_ids` links back to complete plans and terms. `shared_room_group_id` and `room_mapping_source: "giata"` identify matched families. The group identity is quote-scoped, not a persistent inventory ID. You do not need to perform room matching yourself. Unmatched offers remain grouped by provider/source room ID, with no cross-provider equivalence claimed. `data.room_grouping` reports mapped coverage or mapping failure. GIATA failure does not discard valid prices. Optional `room_groups[].images[]` contains up to eight sourced room photos, with URL, source provider/room ID and match method. Photos come from an exact provider room ID or a GIATA-confirmed room family; hotel-level photos are not substituted for missing room photos. Original offers retain `room_images[]` when available. Room groups and provider minimum prices cover **the full quoted session**, so cheaper offers from one provider cannot hide other providers behind transport pages. Raw `offers[]` are paginated; follow the free quote pages for all rate-plan details. Only offers with confirmed mandatory taxes and fees are eligible as comparable group/provider minima. If none is eligible, the minimum is null and provider status is `incomplete_price`. All original offers remain available. For example, Booking can return an incalculable mandatory city tax in its excluded charges. That offer has `unconfirmed_mandatory_fees` and is not eligible as an all-in minimum. A Japanese accommodation tax may still be payable at the hotel when the provider does not itemize it; an absent fee amount is not zero. Different currencies and incompatible price scopes remain separate. For the same GIATA family, requested_stay and all_requested_rooms both cover the full requested party and form one group with canonical price_scope requested_stay. Original offers retain their source scope; per-room prices are not merged with whole-party prices. A missing source room name can appear as `Room `; the provider room ID remains the reliable key. `returned_offer_count` is the total normalized offer count in the session, not the current page size. | Provider | Lowest-rate maximum rooms | Room-detail maximum rooms | | --- | --- | --- | | expedia | 8 | 8 | | booking | 8 | 8 | | agoda | 8 | 8 | | brek | 8 | 8 | Unsupported operations return an explicit provider status; they do not reuse a single-room price. Agoda requests up to 100 supplier rates; do not describe that response as every possible Agoda offer. [Filters & sorting: complete field reference](/docs/filters.html) ## Request fields | Field | Required | Type | Details | | --- | --- | --- | --- | | `hotel_id` | Required | string | 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 | ### 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](/docs/filters.html). 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](/v1/capabilities). ## 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. ```bash curl 'https://www.hoteluse.dev/v1/rates/rooms' \ -H "Authorization: Bearer $HOTELUSE_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: replace-with-a-unique-operation-id' \ --data '{ "hotel_id": "hu_69450c903d9c06226f1ce17b", "context": { "check_in": "2026-11-12", "check_out": "2026-11-14", "rooms": [ { "adults": 2, "children_ages": [] } ], "currency": "USD", "market": { "residency_country": "US" } }, "page_size": 200 }' ``` ## 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. ```json { "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, "max_offers_returned": 100 }, { "provider": "brek", "status": "complete", "upstream_requests": 3, "completed_requests": 3, "failed_requests": 0 } ], "upstream_requests": 6, "hotel_id": "hu_69450c903d9c06226f1ce17b", "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" }, "returned_offer_count": 242, "offers": [ { "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:47.489Z" }, { "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:47.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:47.319Z" }, { "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": [ { "deadline": "2026-10-21T17:50:47.377Z", "type": "amount", "value": 423.1, "currency": "USD" } ] }, "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:47.377Z", "maximum_occupancy": { "adults": 2, "children": null, "total": 2 }, "available_rooms_at_price": 9, "payment_policy": { "prepayment_required": true, "timings": [ "pay_online_now" ] } }, { "offer_id": "offer_32a8de813c2d9951dfb57f87e22e", "provider": "booking", "hotel_id": "hu_69450c903d9c06226f1ce17b", "shared_room_group_id": null, "currency": "USD", "room_name": "Room 18067308", "external_room_id": "18067308", "meal_plan": "no_plan", "cancellation": { "refundable": false, "free_cancellation_until": null, "summary": null, "penalties": [ { "deadline": "2026-10-21T17:50:47.377Z", "type": "amount", "value": 433.22, "currency": "USD" } ] }, "conditional_charges": [], "price_scope": "requested_room", "stay_total": { "amount": "501.04", "currency": "USD" }, "price": { "base": "433.22", "taxes_and_fees": "67.82", "pay_at_property": null, "stay_total": "501.04", "currency": "USD" }, "taxes_and_mandatory_fees_included": true, "checked_at": "2026-10-21T17:50:47.377Z", "maximum_occupancy": { "adults": 2, "children": null, "total": 2 }, "available_rooms_at_price": 9, "payment_policy": { "prepayment_required": true, "timings": [ "pay_online_now" ] } }, { "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:47.343Z" } ], "next_cursor": "example_expired_cursor", "reuse_until": "2026-10-21T18:00:47.763Z" }, "usage": { "hotel_record_units": 0, "search_calls": 0, "room_calls": 1, "trial_units_used": 1, "paid_units": 0, "paid_usd": "0.000", "unit_price_usd": "0.060", "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. ## Real room types and prices Selected room minima from the captured session, 2026-11-12 to 2026-11-14, 2 adults, 1 room, USD. These are provider-specific room IDs; rows do not assert that rooms match across providers. | Provider | Room ID | Room name | Meal plan | Lowest stay total | | --- | --- | --- | --- | --- | | brek | `1252232395` | ROOM, KING BED, SOFA | null | $255.58 | | brek | `1442250655` | ROOM, 2 QUEEN BEDS, SOFA | null | $255.58 | | expedia | `192500` | Room, 1 King Bed with Sofa bed, Balcony - No-Refunds | room_only | $489.44 | | booking | `18067302` | Room 18067302 | no_plan | $489.45 | | booking | `18067308` | Room 18067308 | no_plan | $501.04 | | booking | `18067320` | Room 18067320 | no_plan | $628.59 | | booking | `18067314` | Room 18067314 | no_plan | $727.98 | | agoda | `3530703` | 1 KING BED with SOFA SLEEPER | room_only | $489.45 | | agoda | `3530871` | 2 Queen Beds With Sofa Sleeper | room_only | $501.04 | The capture contains 242 offers. [Download all normalized offers](/docs/examples/all-room-offers.json). The first transport page and its original `returned_offer_count` are in the [full response JSON](/docs/examples/get_room_rates.json). ## Read an offer correctly | Field | Meaning | | --- | --- | | `offer_id` | This provider-specific room/rate/occupancy option. | | `external_room_id` | Provider room identifier. One room can have multiple offers. | | `stay_total` | Amount and currency for the whole requested stay, using the reported price scope. | | `price_scope` | When present, use it to interpret the requested occupancy; Booking single-room offers use requested_room. | | `price.pay_at_property` | Included amount due at the hotel when known. Null means unknown, not zero. | | `taxes_and_mandatory_fees_included` | Only true confirms that mandatory fees are included. Unknown-fee offers are not eligible for lowest-price comparison. | | `currency_conversion` | When present, the source currency, fresh FX rate, premium and expiry. Converted totals are display estimates. Brek uses its 1% FX premium only on prepaid amounts. | | `mandatory_fees` | Original local-currency hotel fees and their display amounts. These are already included in stay_total; do not add them again. Local fees have no room markup or FX premium. | | `cancellation` | Refundability and penalty schedule. Local deadlines include time_basis, timezone and local fields. Do not convert a hotel-local date to UTC without its timezone. | | `maximum_occupancy` | Supplier adult/child/total capacity where available. | | `payment_policy` | Payment timing and prepayment requirements where provided. | ## 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. ```json { "quote_session_id": "qs_from_your_live_response", "cursor": "cursor_from_your_live_response" } ``` [Pricing and limits](/docs/pricing-and-limits.html) · [Errors and retries](/docs/errors-and-retries.html). --- Source: https://www.hoteluse.dev/docs/pricing-and-limits.html # Pricing, limits & coverage ## Start free, then top up Signup credits are issued once per account: 50 destination searches, 50 room calls and 1,000 hotel information units. They do not renew monthly. | Operation | Price after signup credits | Billing unit | | --- | --- | --- | | search_hotels | $0.04 | One completed destination search, including provider lookups | | get_room_rates | $0.06 | One hotel and itinerary; quote pages are free | | get_hotel | $0.005 | One newly read hotel version; repeat reads of the same version are free | Add $10–$1,000 to your prepaid balance when you need more. No subscription or automatic top-ups. [Estimate your cost](/#pricing). ## Completed calls and retries Completed empty and partial results use one call. Invalid requests and total provider failures use no credits. Search and room quote pages reuse the same session for up to 10 minutes and add no call charge. Reuse an Idempotency-Key for uncertain retries for up to 24 hours. ## Account and service limits Default account limits: 60 hotel requests per minute, including up to 10 new live price calls, and one concurrent request across keys and MCP. Approved accounts can have a different policy. A 429 response includes Retry-After. Destination searches consider up to 1,000 matching hotels. Inspect coverage and provider status before describing results as exhaustive. Hotel information returns one hotel per lookup, with a self-serve account limit of 10,000 distinct hotels. Adding balance does not change that limit. Room responses page up to 200 offers. ## Provider coverage | Provider | Search | Room rates | | --- | --- | --- | | expedia | Supported | Supported | | booking | Supported | Supported | | agoda | Supported | Supported | | brek | Supported | Supported | Provider mappings, stay dates, occupancy, supplier availability and deadlines determine actual coverage. Missing mappings, no availability, unsupported requests and provider errors are distinct states. [Capabilities](/v1/capabilities) reports enabled providers and deployment limits. [Errors and retries](/docs/errors-and-retries.html) · [Contact support](mailto:leo@hoteluse.dev). --- Source: https://www.hoteluse.dev/docs/errors-and-retries.html # Errors, retries & idempotency ## HTTP errors | Status | Meaning | Action | | --- | --- | --- | | 400 | Invalid input | Fix the request; no charge. | | 401 | Missing, invalid or revoked bearer key | Check or rotate the key. | | 402 | Insufficient units/balance or caller max_units exceeded | Check usage, authorized budget and dashboard balance. | | 403 | Static access cap reached, or invalid browser origin | Contact support about hotel information access, or correct browser origin. | | 404 | Hotel or quote session not found/expired | Check the ID; expired quote pages require a new search. | | 409 | Idempotency key conflict or operation conflict | Reuse the same key only for the same body and endpoint. | | 422 | No enabled provider mapping supports this request | Inspect mappings and occupancy; no provider call was billed. | | 429 | Account minute or concurrency limit | Respect Retry-After; no charge. | | 503 | No provider completed, provider/configuration unavailable, or billing confirmation pending | Retry safely as described below. | | 504 | Operation deadline exceeded | Retry with the same Idempotency-Key; inspect credits_charged for an uncertain billing outcome. | ```json { "error": { "code": "providers_unavailable", "message": "No provider completed the price request. No credits were charged. Retry later.", "credits_charged": false } } ``` ## Safe retries Send a unique `Idempotency-Key` (at most 128 characters) for each intended operation. Keep the same key, endpoint and body for network timeouts or an uncertain outcome. Successful replays return the stored result for 24 hours without another debit. A replay keeps the original receipt and unit values with `usage.replayed: true`; count that receipt once when aggregating usage. A different body with the same key returns 409. If `error.code` is `billing_confirmation_pending`, `credits_charged` can be null while the ledger recovers. Keep the same Idempotency-Key; do not generate a second key and risk starting another intended call. Honor Retry-After on 429. Use bounded exponential backoff for temporary upstream failures. The default account allows one new hotel request at a time; avoid parallel fan-out across keys. ## A 200 can be partial A provider can fail while others return useful results. Inspect `data.provider_results`, hotel-level provider statuses and `data.coverage`. Never turn a timeout or missing mapping into “no rooms available.” Completed no-availability responses are valid billed searches. Malformed supplier bodies are errors. ## Time budgets and failure isolation Each hotel operation has a 30-second server deadline, including destination resolution, catalog access, provider work, grouping and persistence. Auto Suggest uses one shared 2.5-second window for suggestion and place resolution. Cold catalog recall starts with up to 8 seconds and may retry once for up to 4 seconds, capped by the operation deadline minus 17 seconds reserved for shopping and finalization. Warm queries return as soon as ready. Supplier shopping has a 15-second phase. Public Expedia, Booking and Agoda HTTP calls use 4 seconds, matching Brek. Wholesale TGX receives up to 10 seconds to collect suppliers, matching Brek, plus up to 2 seconds for network/response handling. A shorter remaining operation budget reduces these limits. Retries share the first dispatch's deadline; they never reset the clock. Room requests reserve 8.5 seconds after shopping for GIATA (5 seconds, then at most a 3-second retry) and 2 seconds for finalization. Valid room prices survive unavailable mapping; unmatched rooms stay in safe provider-specific groups. Each supplier fails independently. A supplier timeout does not turn successful competitors into a failed tool call. A complete provider outage returns an error without consuming a call. Missing optional star metadata stays unknown; unfiltered shopping continues. Explicit star filters use verified matches only. If some metadata could not be checked, `catalog_quality` and lower-bound coverage describe the limitation. If no candidate can be verified for that filter, retryable `star_classification_unavailable` is returned instead of false sold-out results. ## Diagnostics `provider_results[].planned_requests` counts planned batches; `dispatched_requests` / `upstream_requests` count actual HTTP starts, including retries. Rejected work before dispatch has zero HTTP starts. `completed_requests`, `failed_requests` and `unstarted_requests` distinguish responses, unsuccessful attempts and batches never sent. A recovered retry can leave a complete result with a failed attempt in its history. `batch_results[]` includes per-batch status, attempts, actual dispatches, `queue_ms`, `http_ms` and sanitized errors. Brek also exposes these in `source_results[]`, identified by 108/118/999 and 127 outside the US. Error `timeout_origin` distinguishes `supplier`, `client_http`, `source_queue`, `operation_deadline` and `client_cancel`. `stage` identifies the failing phase. `data.timings` reports catalog, quote, grouping and total service time. Supplier bodies, credentials and raw messages are excluded. Source start rates are shared across developer, website and consumer clients and across HotelUse replicas: Expedia at most 6 starts/second, Booking/Agoda and Brek 108/118/999 at most 10, source 127 at most 2. Public and detailed calls use at most four workers per provider; wholesale listing uses six workers per source. Minute budgets are additional to these start limits. Temporary Brek failures may retry once inside the same budgets and do not add a HotelUse call charge. The Claude and ChatGPT consumer connector has no fixed live-search quota per minute and no IP-based request quota by default. Shared platform egress IPs do not identify individual travelers. The service admits up to 12 concurrent uncached operations; identical in-process searches coalesce and brief response caches avoid repeated shopping. A global 12,000 MCP requests/minute circuit breaker protects control-plane overload. Reaching service concurrency or supplier capacity can still return a retryable 429 or partial provider coverage. This is service backpressure, not a paid plan or a consumer credit allowance. Consumer supplier admission has a separate 4,320 upstream starts/minute budget within a 4,800 shared total; developers retain 480. The per-supplier start rates above remain unchanged and can constrain dense-city throughput before that minute budget. Higher ingress limits do not guarantee unlimited quote throughput. Optional per-minute and per-IP guards can be enabled by operators; zero disables them. These settings apply to /mcp/search only. Account billing and developer /mcp limits remain separate. Cancelling one subscriber does not cancel another subscriber's shared search. ## Report an issue Include endpoint, request_id when returned, dates, currency, occupancy and provider status. Validation errors can occur before a request_id is issued. Remove API keys, cookies and personal details. [Contact support](mailto:leo@hoteluse.dev). --- Source: https://www.hoteluse.dev/docs/mcp.html # MCP connection Connect a client that supports Streamable HTTP and bearer headers. The endpoint is `https://www.hoteluse.dev/mcp`. Use the same HotelUse account API key as HTTP. ```json { "mcpServers": { "hoteluse": { "url": "https://www.hoteluse.dev/mcp", "headers": { "Authorization": "Bearer YOUR_HOTELUSE_API_KEY" } } } } ``` This developer connection uses an API key and the account's normal usage billing. Enter the key through your client's secret settings; header/environment syntax varies by client. The consumer search connector below uses a separate no-authentication endpoint. ## Consumer search connector [Connect Claude](/docs/mcp/claude.html) · [Connect ChatGPT](/docs/mcp/chatgpt.html) · [Build with AI agents](/docs/mcp/ai-agents.html). Connect ChatGPT, Claude or another MCP Apps host to `https://www.hoteluse.dev/mcp/search` with **No authentication**. It exposes three tools: `search_hotels`, `get_room_rates` and `get_hotel`, returning structured multi-provider prices and an interactive comparison UI. It does not require a HotelUse account, API key, prepaid credit or per-user free allowance. Provider links first use a signed HotelUse /go/ URL, then redirect to the provider with affiliate tracking preserved. Links expire with the 10-minute quote. A booking may earn HotelUse a commission. Booking and payment happen at the provider. ```json { "mcpServers": { "hoteluse": { "type": "streamable-http", "url": "https://www.hoteluse.dev/mcp/search" } } } ``` Example consumer search arguments: `destination` is a place name, with hotel-local `check_in` and `check_out` (today or later), or `date_intent: "tonight"` without explicit dates. Optional `country` disambiguates the destination. Omitted `rooms` means two adults in one room. The consumer connector accepts one to three rooms so its booking handoff matches provider support. ```json { "destination": "Bellevue, Washington, US", "check_in": "2026-11-12", "check_out": "2026-11-14", "currency": "USD", "locale": "en-US", "rooms": [ { "adults": 2, "children_ages": [] } ] } ``` For tonight, send `{ "destination": "Bellevue, Washington", "country": "US", "date_intent": "tonight", "rooms": [{ "adults": 1, "children_ages": [] }], "hotel_filters": { "star_ratings": [4, 5] } }`. The server resolves the destination local date, including after UTC midnight. It never moves tonight to tomorrow merely because UTC advanced. The returned `data.context.check_in`, `check_out` and `date_context` show the actual itinerary and local time zone. The same `date_intent` option is available for room queries. New tonight searches resolve again after local midnight; quote pagination retains its original dates until expiry. Use a returned `hotel_id` with `get_room_rates` and the same returned dates, currency and occupancy. Returned offers include a `booking_url` when a safe provider link is available. A Brek link resolves the B2B hotel to Brek's distinct inventory ID before handoff. Search/room pagination uses `quote_session_id` and `cursor`; quote sessions expire after 10 minutes. The consumer response has `channel: "consumer_connector"` and `billing.model: "affiliate"`, rather than a developer usage receipt. The portable [plugin package](/downloads/hoteluse-plugin.zip) is prepared for host installation and platform review. This endpoint is available independently; it is not evidence of an approved listing in either platform's directory. Hosts without MCP Apps UI can use the structured results and links. Consumer traffic has separate, configurable service capacity and upstream protections; it does not use developer account rate limits or credit allowances. Developer API usage is billed separately from the consumer connector. ## Search filters Consumer search accepts the same hotel_filters and rate_filters as the HTTP API. Star classification, normalized guest score, review count, facilities, property types, distance and whole-stay budgets have explicit fields. Hotel star classifications use Expedia metadata when one unambiguous Expedia mapping is available; other hotels retain the catalog classification. `star_classification` reports the source, verification status and check time. Provider classifications may differ. Missing provider classifications stay unknown, and guest-review scores never fill a missing star rating. HotelUse caches classification facts for up to seven days independently of live prices; it never changes source B2B records. Read [Filters & sorting](/docs/filters.html) before constructing a request. Preserve desired rate_filters in room follow-ups; search_quote_session_id inherits omitted dates, occupancy, currency, language, residency, providers and rate_filters from the exact search; explicit arguments override inherited values, except device must remain unchanged. Send rate_filters: {} to clear inherited rate constraints. ## Device and mobile rates Developer price calls accept `context.device`; consumer MCP price tools accept flat `device`. Allowed values are `desktop` (default), `mobile_web` and `mobile_app`. Device selection is automatic for consumer MCP clients. ChatGPT's optional `_meta["openai/userAgent"]` supplies a best-effort traveler hint, like the existing country/locale metadata. A recognized client hint takes priority over a model-supplied desktop/mobile-web guess. If tool metadata is absent, the embedded app can use MCP Apps `hostContext.platform` / `userAgent` or the actual browser user agent. A late mobile hint refreshes an initial unknown-device quote at most once and updates model context. Missing or unrecognized signals default to desktop. Server HTTP headers, window width and destination are not device signals. Users are never asked to select a device. These hints do not authorize restricted rates, and a native ChatGPT/Claude mobile app does not automatically qualify as an approved HotelUse native-app integration. Native-app rates require an approved app integration. Mobile rates are not always cheaper and are only for eligible travelers. | Device | Expedia source | Booking platform | Agoda platform | | --- | --- | --- | --- | | desktop | browser | desktop | Desktop | | mobile_web | browser | mobile | MobileWeb | | mobile_app | mobileapp | mobile | MobileApp | For example, add `"device": "mobile_web"` inside a developer request's `context`, or to consumer tool arguments. Copy a consumer search's `search_session_id` into the room call's optional `search_quote_session_id`. The server inherits omitted dates, room occupancy, currency, language, residency, providers and rate filters from that exact search, even if current client metadata changes. For example, a 1-adult search stays 1 adult when the room call supplies only hotel_id and search_quote_session_id. Explicit arguments can change a new quote, except its device must remain unchanged. An explicit empty rate_filters object clears inherited rate constraints. The reference expires with the 10-minute quote; conflicting device changes are rejected. Otherwise reuse the returned device context for room queries and booking. Quote-session pagination preserves the original context and cannot switch devices. Cached desktop and mobile results are separate. Provider-generated booking links are preserved; their rates still require an eligible device at the provider. Do not present an app rate as universally bookable. Expedia mobile-web requests use browser rates, not app rates. Brek wholesale source selection and markup are unchanged. ## Currency and language Explicit `context.currency`, `context.locale` and `context.market.residency_country` win on the developer tools. Consumer tools use flat `currency`, `locale` and `residency_country` arguments. When host metadata is absent, Claude may supply optional `user_locale` and `user_location_country` from its traveler context. Trusted host hints take priority over these fallback hints; explicit traveler choices still win. These fields never set the hotel destination or its local stay dates. For MCP calls, omitted preferences may be filled from client metadata: `openai/locale` (then `webplus/i18n`) and `openai/userLocation.country`. Currency follows visitor country, then locale region, then USD. Residency uses visitor country when provided, otherwise US. Do not infer traveler preferences from the hotel destination. HTTP requests without these fields continue to default to USD/US. Booking and Agoda receive the requested currency. Our current Expedia key is bound to the US point of sale, so Expedia is queried and booked in USD. Other Expedia display currencies are reference estimates using a fresh exchange snapshot, with no added FX premium. Room links preserve the supplier-generated room/rate-plan URL. Brek is also queried and booked in USD; other display currencies use the fresh Brek exchange feed and its 1% FX premium on the prepaid amount. Local hotel fees retain their original amount and currency, without that premium. currency_conversion records the source currency, original full-stay total (source_stay_total), original prepaid amount (source_prepaid_total), reported pay-at-property amount (source_pay_at_property), booking_currency, rate, premium, timestamp and expiry. Converted amounts are reference estimates; they do not promise checkout or card settlement in that display currency. Local fees can still be collected in their original currency. Expired or missing FX fails the provider explicitly. No USD amount is relabeled as JPY. Provider content languages vary. Unsupported provider locales fall back to English; static records and room names can retain their source language. UI labels currently support English, Chinese, Japanese and Spanish, with localized amount formatting. ## Developer tools | Tool | Reference | | --- | --- | | `search_hotels` | [Search hotels](/docs/api/search-hotels.html) | | `get_hotel` | [Get hotel information](/docs/api/get-hotel.html) | | `get_room_rates` | [Get room rates](/docs/api/get-room-rates.html) | ## Official JavaScript SDK example Install `@modelcontextprotocol/sdk` from npm in your application. This example lists tools and reads a real hotel record; the tool call consumes the same account data units as HTTP. ```javascript import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; const client = new Client({ name: 'my-hotel-agent', version: '1.0.0' }); try { await client.connect(new StreamableHTTPClientTransport(new URL('https://www.hoteluse.dev/mcp'), { requestInit: { headers: { Authorization: 'Bearer ' + process.env.HOTELUSE_API_KEY } } })); console.log((await client.listTools()).tools.map(tool => tool.name)); const result = await client.callTool({ name: 'get_hotel', arguments: { hotel_id: 'hu_69450c903d9c06226f1ce17b' } }); if (result.isError) throw new Error(JSON.stringify(result)); console.log(result.structuredContent.data.hotel); } finally { await client.close(); } ``` ## MCP result envelope Tool results include the HTTP result in `structuredContent` and a text representation in `content`. Protocol request IDs are separate from the HotelUse `request_id` in that structured envelope. Inspect `isError` before reading data. HTTP and MCP share pricing, access caps and rate limits. Result pages use the same tool with `quote_session_id` and `cursor`. [Quickstart](/docs/quickstart.html) · [Agent setup guide](/agent.md). --- Source: https://www.hoteluse.dev/docs/mcp/claude.html # MCP for Claude Search hotels, compare provider prices and explore room options inside Claude. No HotelUse account, API key or prepaid credits required. ## Connect HotelUse 1. In Claude, open **Customize → Connectors**. 2. Choose **Add connector → Add custom connector**. 3. Name it **HotelUse** and enter `https://www.hoteluse.dev/mcp/search`. 4. Continue with **No sign-in**, add the connector, then choose **Connect**. 5. In a new conversation, enable HotelUse in the tools menu. Custom connector availability depends on your Claude plan and workspace settings. This is a direct connection; a public directory listing requires a separate platform review. ## Try a search Ask: “Find hotels in Bellevue, Washington for November 12–14, 2026, two adults, one room, in USD. Compare Expedia, Booking, Agoda and Brek.” Replace these dates with your own future stay. Hotel cards show photos, address, star classification and key facilities, followed by four provider prices in **compact rows**, sorted from lowest to highest price with unavailable quotes last, with stay totals, nights, requested room count and mandatory taxes and fees clearly labeled. Destination hotel order defaults to nearest 5 km bands first and greatest Brek price advantage within each band; provider rows themselves always sort by price. The top of each card highlights the lowest returned eligible stay total. Search results contain hotel summaries and provider minimum prices, without room offers. Click a provider price to open its booking page. To compare rooms, ask: “What room options and prices does the first hotel have for the same dates?” This calls a separate room tool and opens the Room options view. Provider filters show room types with a quote from that provider. “No quote for this room” means that provider has no comparable quote in that room group; it does not mean the hotel is sold out. Different room types, cancellation and meal terms can apply; check the selected provider’s final terms. Click a provider price to open that provider's booking page. HotelUse does not reserve rooms or collect payment. Booking links first pass through a signed HotelUse /go/ URL, then redirect to the named provider with affiliate tracking intact. They expire with the 10-minute quote; request a fresh quote after expiry. HotelUse may earn a commission. ## Follow-up questions Changing the destination, dates, guests, filters or sort starts one new `search_hotels` call with the unchanged stay details preserved. A previous result page is not the full set of matching hotels. “Nearest first” uses `sort: distance_asc`; “Cheapest first” uses `sort: stay_total_asc`; “4-star only” uses `hotel_filters.star_ratings: [4]`, while “4- and 5-star only” uses `[4,5]`. Minimum 4 stars also admits fractional classifications such as 4.5. For “rooms at the first hotel,” use the exact `hotel_id` from the most recent list and call `get_room_rates` directly with that search’s `search_session_id` as `search_quote_session_id`. For pet or parking policies, call `get_hotel` directly. Neither needs another destination search. Explaining existing prices does not itself require a new quote. A room query already includes every returned room group and its provider minimum prices. Asking for all room options needs one room-tool call; expanding the cards is local and does not query suppliers again. After a connector tool update, refresh its tools list in Claude and start a new conversation; an existing conversation may retain old tool definitions. ## Tools | Tool | Input | Result | | --- | --- | --- | | search_hotels | Destination, hotel-local dates or date_intent: tonight; optional guests, currency and language | Matching hotels and the lowest eligible full-stay price from each provider | | get_room_rates | HotelUse hotel_id, or Full hotel_name (destination optional); explicit dates and guests, or search_quote_session_id | Separate Room options view with server-grouped room types and provider prices | | get_hotel | HotelUse hotel_id, or Full hotel_name (destination optional for disambiguation); no dates needed | Address, photos, facilities, star classification and descriptions; no live prices | ## Hotel information without dates Ask: “What are the address, facilities and star rating of Hilton Bellevue?” The public `get_hotel` tool returns traveler-facing facts without a rate request. It accepts a returned HotelUse ID, or a full hotel name. Add the destination to disambiguate names shared by several properties. Ambiguous hotel names return candidates for confirmation before any live room query. This facts tool returns hotel information for trip planning. Room matching happens on the server. Unmatched provider rooms remain separate; HotelUse does not claim that similarly named rooms are identical. All raw rate plans remain in the structured tool response. ## Language and currency Ask for your preferred currency and language. Explicit preferences take priority. UI labels support English, Chinese, Japanese and Spanish; supplier room descriptions may remain in their source language. Brek USD quotes and local-currency taxes can be converted using a fresh FX snapshot; the UI labels converted amounts and the original local fee. Other unsupported supplier currencies return an explicit provider error rather than a relabeled price. ## When a request cannot finish Service capacity and supplier availability can temporarily limit requests. Retry after the indicated delay. You do not need to buy developer credits to use this connector. [Developer support](mailto:leo@hoteluse.dev?subject=HotelUse%20Claude%20support) · [Privacy](/privacy.html). --- Source: https://www.hoteluse.dev/docs/mcp/chatgpt.html # MCP for ChatGPT HotelUse gives ChatGPT hotel search, four-provider price comparisons and grouped room options. No HotelUse account or API key is needed. ## Add a custom connection Where your ChatGPT plan supports custom MCP servers, open **Plugins → Add custom MCP server**. Enter `https://www.hoteluse.dev/mcp/search`, choose **No authentication**, review the connection details and create the plugin. Workspace administrators may need to allow custom connections. For clients that install portable plugin packages, [download the HotelUse package](/downloads/hoteluse-plugin.zip). A custom installation is separate from an approved public directory listing. ## Search, compare, then choose a room Ask: “Find Bellevue hotels for November 12–14, 2026, two adults, one room, USD. Compare Expedia, Booking, Agoda and Brek.” Use future dates for a new search. Each hotel shows photos, address, star classification and key facilities, with a lowest stay total followed by **four compact provider rows**, sorted from lowest to highest price with unavailable quotes last. Destination results use nearest 5 km bands first, then lowest full-stay price within each band. Totals identify nights and the requested room count. Search cards contain no room-level offers or internal hotel expansion. A provider price opens that platform directly. Ask “Show room options for the first hotel for the same dates” to get a separate Room options view with grouped room types and four-provider prices. All returned room groups and provider minimum prices arrive in that one call; no additional raw-offer pages are needed. Expand remaining room cards or filter rooms by provider locally. “No quote for this room” applies to that room group, not the hotel as a whole. Click a provider price to open that platform. Booking and payment happen there. HotelUse may earn affiliate commission from a booking. The UI uses the same MCP Apps resource as Claude. Clients without interactive UI support can read structured results and provider links. Search pages can be loaded without repricing the same ten-minute quote session. ## Safe comparisons Displayed comparable totals include confirmed mandatory taxes and fees. Prices can change at checkout. “Not available” means no comparable quote is shown in that provider slot; the structured response distinguishes missing mappings, unsupported occupancy, errors and availability. Currency, language, guests and stay dates carry through to the room query and booking handoff. HotelUse does not silently substitute a different currency or a single-room price for a multi-room request. ## Support This connector has its own service capacity protections and does not consume developer account credits. For a custom hotel search application, use the [developer MCP](/docs/mcp/ai-agents.html). [Developer support](mailto:leo@hoteluse.dev?subject=HotelUse%20ChatGPT%20support) · [Privacy](/privacy.html). --- Source: https://www.hoteluse.dev/docs/mcp/ai-agents.html # MCP for AI agents Choose the connection that matches your agent's job. | | Hotel search connector | Developer MCP | | --- | --- | --- | | Endpoint | https://www.hoteluse.dev/mcp/search | https://www.hoteluse.dev/mcp | | Authentication | None | HotelUse bearer API key | | Tools | search_hotels, get_room_rates, get_hotel | search_hotels, get_room_rates, get_hotel | | Use case | Traveler hotel comparisons and booking links | Hotel search, room pricing and hotel information for applications | | Billing | No HotelUse account credits; affiliate-supported | Developer signup credits, then prepaid usage | ## Public hotel search ```json { "mcpServers": { "hoteluse": { "type": "streamable-http", "url": "https://www.hoteluse.dev/mcp/search" } } } ``` Send flat arguments: `destination`, `check_in`, `check_out`, optional `rooms`, `currency`, `locale` and `residency_country`. Omitted rooms mean two adults in one room. The result includes a HotelUse ID for follow-up room requests and safe provider booking URLs. Use the MCP Apps resource for interactive four-row provider comparisons, or consume structured results directly. ## Brek multi-room booking The public search connector links directly to Brek booking. Brek supports two or three rooms of the same supplier room type. HotelUse compares only those eligible Brek combinations for destination searches and room options; it does not combine separate one-room prices. Requests for more rooms can still return other supported providers. The authenticated developer API preserves raw supplier room combinations and its existing room-count limits. ## Three independent requests ```json { "name": "search_hotels", "arguments": { "destination": "Bellevue, Washington", "check_in": "2026-11-12", "check_out": "2026-11-14", "currency": "USD", "rooms": [ { "adults": 2, "children_ages": [] } ] } } ``` Search returns `data.view: "hotel_search"`, hotel summaries and provider minimum stay totals. No room options are included. The exact returned `hotel_id` identifies the hotel in follow-up calls. ```json { "name": "get_room_rates", "arguments": { "hotel_name": "Hilton Bellevue", "destination": "Bellevue, Washington", "check_in": "2026-11-12", "check_out": "2026-11-14", "currency": "USD", "rooms": [ { "adults": 2, "children_ages": [] } ] } } ``` Room queries return `data.view: "room_options"`, grouped room types, provider prices and rate terms for this hotel and itinerary. The consumer MCP returns all grouped room options and provider minimum prices in one call, with `room_options_complete: true` and `next_cursor: null`. `raw_offer_page` describes the included raw-offer sample; it does not indicate missing room groups. Do not fetch additional raw pages to answer ‘all room options and prices.’ Expand room cards locally. Raw supplier rate-plan pagination remains available through the authenticated developer API and developer MCP. Prefer a returned `hotel_id` when available; do not send both an ID and a hotel name. An exact ID is authoritative; optional destination, country and region hints carried over from search are accepted and do not change the selected hotel. A name must resolve to one active catalog record. Otherwise the tool returns `status: "hotel_selection_required"` with candidate IDs and requests no live rates. ```json { "name": "get_hotel", "arguments": { "hotel_name": "Hilton Bellevue", "destination": "Bellevue, Washington", "locale": "en-US" } } ``` The public metadata tool returns `data.view: "hotel_details"` and `data.hotel`: curated address, photos, facilities, descriptions, star classification, sourced guest ratings, consecutive positive review count, and pet/parking policies. Guest ratings identify their provider; review counts are not added across providers. A `fee: null` with `fee_status: "not_provided"` means the catalog has no exact amount. Paid parking and pets allowed do not imply any particular fee or restrictions. It needs no stay dates and makes no live supplier price call. It returns model-readable facts without a price comparison widget. Use these hotel facts to answer traveler questions without starting a price search. ## Supported developer tools ```json { "mcpServers": { "hoteluse": { "url": "https://www.hoteluse.dev/mcp", "headers": { "Authorization": "Bearer YOUR_HOTELUSE_API_KEY" } } } } ``` Create an account and API key through the [Quickstart](/docs/quickstart.html). Store the key in your client's secret settings; exact header and environment syntax varies by client. Never commit it or expose it in browser code. Begin with `search_hotels` and a destination. Use a returned hotel_id with `get_hotel` for hotel information or `get_room_rates` for room groups, prices and terms. Developer tools use the HTTP request structures, including nested `context`. Consumer tools use flat itinerary arguments. The two schemas are intentionally distinct; read tools/list before calling. [Full MCP reference](/docs/mcp.html) · [API reference](/docs/api/search-hotels.html) · [Pricing and limits](/docs/pricing-and-limits.html) · [Developer support](mailto:leo@hoteluse.dev?subject=HotelUse%20MCP%20support).