HotelUse - Hotel Metasearch

Search a destination or latitude/longitude (with country) for explicit hotel-local dates (including today), or date_intent: tonight. Tonight is resolved server-side in the destination time zone, never UTC. Returns hotel summaries and the lowest eligible full-stay total from Expedia, Booking, Agoda and Brek, with direct provider booking links. Search starts at a 20 km core radius, expanding to 40 km then 60 km while fewer than 50 matching static candidates exist, within the same tool call and deadline. Explicit max_distance_km disables expansion. Providers are queried once after the final candidate scope is chosen. Default order is nearest 5 km distance bands first, then greatest Brek price advantage over the cheapest other provider in each band. The advantage uses comparable full-stay totals in the same currency; missing comparisons go last within their band. Preserve the returned hotel order unless the user requests another sort. Supports star ranges or exact stars, guest-review minimum and review count, facilities, property types, distance and full-stay price budgets. Hotel and rate filters can be combined; budgets cover all nights and requested rooms, including mandatory taxes and fees. Guest scores and hotel star classifications have separate filters. no_matching_offer means prices/terms failed the requested filters, not sold out. Room types and room-level rate plans are not included. No HotelUse account or API credits required. Device detection is automatic with a desktop fallback. For a fresh search supply destination or latitude/longitude with country, and either check_in/check_out or date_intent. Search pagination accepts only quote_session_id and cursor. Omit unknown optional values; do not send null. On follow-ups that change destination, dates, guests, hotel/rate filters or sort, call search_hotels again once with the updated criteria and preserve unchanged itinerary/preferences from the latest relevant search. Do not filter or reorder an earlier result page and present it as a new destination search: that page may omit matching hotels. For nearest, closest, or distance order use sort: distance_asc. The geographic_scope.radius_km value is the search radius, never any hotel’s distance. Per-hotel distance_meters is measured from the destination center. For cheapest hotels use sort: stay_total_asc. For "4-star only" use hotel_filters.star_ratings: [4]; for "4- and 5-star only" use [4,5], not star_rating_min: 4 (which includes 4.5). Never broaden explicit criteria silently. Omit providers unless the user requests specific providers; the server handles occupancy support. A successful partial response is the result of this search: show the returned prices and do not automatically repeat the search to fill missing provider quotes. An explicit user refresh calls the tool again. Pagination with quote_session_id/cursor is only for unchanged criteria.

{
  "type": "object",
  "properties": {
    "destination": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "region": {
      "type": "string"
    },
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Search center latitude. Supply together with longitude. Explicit coordinates take precedence over city/region."
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Search center longitude. Supply together with latitude."
    },
    "hotel_filters": {
      "type": "object",
      "properties": {
        "amenities": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 20,
          "description": "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": {
          "type": "number",
          "minimum": 0,
          "maximum": 5,
          "description": "Minimum hotel star classification, distinct from guest reviews."
        },
        "star_rating_max": {
          "type": "number",
          "minimum": 0,
          "maximum": 5
        },
        "star_ratings": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5
          },
          "minItems": 1,
          "maxItems": 5,
          "uniqueItems": true,
          "description": "Accepted exact star classifications; intersects with any min/max range."
        },
        "review_score_min": {
          "type": "number",
          "minimum": 0,
          "maximum": 10,
          "description": "Minimum guest score normalized to 10, using the displayed review_summary provider. Unknown scores/scales do not qualify."
        },
        "review_count_min": {
          "type": "integer",
          "minimum": 0,
          "description": "Minimum review count from that same review_summary provider. Counts are not added across providers."
        },
        "property_type": {
          "type": "string"
        },
        "property_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "maxItems": 12,
          "uniqueItems": true,
          "description": "Accept any of these source property types. Use instead of property_type."
        },
        "name_contains": {
          "type": "string"
        },
        "max_distance_km": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 20,
          "description": "Maximum straight-line distance from the resolved destination center, up to 20 km. Requires a city/destination or latitude/longitude."
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "sort": {
      "type": "string",
      "enum": [
        "distance_brek_savings_desc",
        "distance_price_asc",
        "stay_total_asc",
        "stay_total_desc",
        "distance_asc",
        "review_score_desc"
      ],
      "default": "distance_brek_savings_desc",
      "description": "For nearest, closest, or sorting by distance use distance_asc (exact straight-line distance ascending). Default: nearest 5 km distance bands first (0–5, 5–10, 10–15, 15–20 km), then greatest Brek price advantage over the cheapest other provider within each band (other provider total minus Brek total, in context.currency). Only comparable full-stay totals including mandatory taxes and fees qualify. Missing comparisons are last within their band; ties use lowest total, distance and hotel ID. Unpriced hotels are last. distance_price_asc retains lowest-price ordering within the same bands. stay_total_asc sorts all matched hotels by total without distance bands. distance_asc uses straight-line distance; stay_total_desc uses descending whole-stay price; review_score_desc uses the displayed normalized guest score, then review count. Unpriced hotels remain last in every order. Sorting happens before pagination."
    },
    "user_locale": {
      "type": "string",
      "minLength": 2,
      "maxLength": 35,
      "description": "Optional traveler locale from client context, such as en-GB. Independent of the hotel destination."
    },
    "user_location_country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "Optional traveler country from client context, used for default currency and residency. Independent of the hotel destination."
    },
    "device": {
      "type": "string",
      "enum": [
        "desktop",
        "mobile_web",
        "mobile_app"
      ],
      "description": "Optional traveler device. Omission uses trusted client hints, then desktop. Room follow-ups inherit the effective search device. Mobile app rates require an approved native-app integration."
    },
    "check_in": {
      "type": "string",
      "format": "date",
      "description": "Hotel-local calendar date; today is allowed in the destination time zone, even after UTC midnight."
    },
    "check_out": {
      "type": "string",
      "format": "date"
    },
    "date_intent": {
      "type": "string",
      "enum": [
        "tonight"
      ],
      "description": "A one-night stay resolved server-side in the destination or hotel time zone. Mutually exclusive with check_in/check_out."
    },
    "rooms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "adults": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8
          },
          "children_ages": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 17
            }
          }
        },
        "required": [
          "adults",
          "children_ages"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 3
    },
    "currency": {
      "type": "string",
      "description": "Requested display currency. Omission defaults to client visitor country, then locale, then USD."
    },
    "locale": {
      "type": "string",
      "description": "Traveler BCP 47 language, such as en-GB, independent of the destination."
    },
    "residency_country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "page_size": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "providers": {
      "type": "array",
      "items": {
        "enum": [
          "expedia",
          "booking",
          "agoda",
          "brek"
        ]
      },
      "uniqueItems": true,
      "minItems": 1
    },
    "rate_filters": {
      "type": "object",
      "properties": {
        "refundable_only": {
          "type": "boolean",
          "description": "Require known refundable terms; unknown terms do not qualify."
        },
        "breakfast_included": {
          "type": "boolean"
        },
        "stay_total_min": {
          "type": "number",
          "minimum": 0,
          "maximum": 100000000,
          "description": "Minimum full-stay amount in context.currency for all requested rooms, including mandatory taxes and fees. Not a nightly price."
        },
        "stay_total_max": {
          "type": "number",
          "minimum": 0,
          "maximum": 100000000,
          "description": "Maximum full-stay amount in context.currency for all requested rooms, including mandatory taxes and fees. Applies to each returned offer before minima."
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "quote_session_id": {
      "type": "string",
      "description": "Copy the exact quote_session_id from the result being paged."
    },
    "cursor": {
      "type": "string",
      "description": "Copy the returned next_cursor exactly. Do not calculate an offset or mix new filters with a quote page."
    }
  },
  "additionalProperties": false
}

Get one identified or named hotel’s room options and provider prices for explicit hotel-local dates (including today), or date_intent: tonight, and occupancy. Tonight is resolved server-side in the hotel time zone. Accepts the exact HotelUse hotel_id from search_hotels, or hotel_name and destination when the ID is unavailable; destination is optional but helps disambiguation. A unique hotel match is required. Returns server-grouped room types, rate terms and full-stay provider prices in a separate Room options view. Provider price links open external booking pages; no reservation is made. Providing search_quote_session_id inherits omitted dates, occupancy, currency, language, residency and rate filters from that exact search. Explicit itinerary changes create a new quote; the search device is preserved. Supply exactly one hotel_id or hotel_name. Supply check_in/check_out, date_intent, or an existing search_quote_session_id for room quotes. All returned room groups are included in the first response; no room pagination is needed. Omit unknown optional values; do not send null. Resolve a hotel follow-up by name or position against the most recent relevant ordered search list. Copy its hotel_id exactly; if unavailable, use hotel_name and destination. Ask only if the hotel is ambiguous. For room options or current room prices call get_room_rates directly, passing search_quote_session_id from that search to preserve its stay and preferences. The first get_room_rates response includes all returned room groups and every provider minimum in room_groups. For all room options and prices, use that complete list after one call; do not paginate raw supplier offers or re-query the same stay. The raw_offer_page count describes supplier rate plans, not additional room types. Users can expand room cards locally without another price query. For undated amenities, policies or other hotel facts call get_hotel directly. Do not repeat a destination search before either hotel-specific tool. Existing returned prices may be explained without refreshing when no new search or current quote is requested.

{
  "type": "object",
  "properties": {
    "hotel_id": {
      "type": "string",
      "pattern": "^hu_[a-f0-9]{24}$",
      "description": "Exact HotelUse hotel_id from a previous result."
    },
    "destination": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "City or region to disambiguate the hotel name."
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "region": {
      "type": "string"
    },
    "user_locale": {
      "type": "string",
      "minLength": 2,
      "maxLength": 35,
      "description": "Optional traveler locale from client context, such as en-GB. Independent of the hotel destination."
    },
    "user_location_country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "Optional traveler country from client context, used for default currency and residency. Independent of the hotel destination."
    },
    "device": {
      "type": "string",
      "enum": [
        "desktop",
        "mobile_web",
        "mobile_app"
      ],
      "description": "Optional traveler device. Omission uses trusted client hints, then desktop. Room follow-ups inherit the effective search device. Mobile app rates require an approved native-app integration."
    },
    "check_in": {
      "type": "string",
      "format": "date",
      "description": "Hotel-local calendar date; today is allowed in the destination time zone, even after UTC midnight."
    },
    "check_out": {
      "type": "string",
      "format": "date"
    },
    "date_intent": {
      "type": "string",
      "enum": [
        "tonight"
      ],
      "description": "A one-night stay resolved server-side in the destination or hotel time zone. Mutually exclusive with check_in/check_out."
    },
    "rooms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "adults": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8
          },
          "children_ages": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 17
            }
          }
        },
        "required": [
          "adults",
          "children_ages"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 3
    },
    "currency": {
      "type": "string",
      "description": "Requested display currency. Omission defaults to client visitor country, then locale, then USD."
    },
    "locale": {
      "type": "string",
      "description": "Traveler BCP 47 language, such as en-GB, independent of the destination."
    },
    "residency_country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "providers": {
      "type": "array",
      "items": {
        "enum": [
          "expedia",
          "booking",
          "agoda",
          "brek"
        ]
      },
      "uniqueItems": true,
      "minItems": 1
    },
    "rate_filters": {
      "type": "object",
      "properties": {
        "refundable_only": {
          "type": "boolean",
          "description": "Require known refundable terms; unknown terms do not qualify."
        },
        "breakfast_included": {
          "type": "boolean"
        },
        "stay_total_min": {
          "type": "number",
          "minimum": 0,
          "maximum": 100000000,
          "description": "Minimum full-stay amount in context.currency for all requested rooms, including mandatory taxes and fees. Not a nightly price."
        },
        "stay_total_max": {
          "type": "number",
          "minimum": 0,
          "maximum": 100000000,
          "description": "Maximum full-stay amount in context.currency for all requested rooms, including mandatory taxes and fees. Applies to each returned offer before minima."
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "search_quote_session_id": {
      "type": "string",
      "pattern": "^qs_[a-f0-9-]{36}$",
      "description": "A search result’s search_session_id. Inherits omitted stay dates, rooms, currency, language, residency and rate_filters from that search. Its device is preserved even if current client metadata changes."
    },
    "hotel_name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100,
      "description": "Hotel name when no exact hotel_id is available. A unique, confident match is required. A full hotel name may be used without a destination; add the destination when ambiguous."
    }
  },
  "additionalProperties": false
}

Get undated facts for one identified or named hotel: address, photos, descriptions, star classification, sourced guest ratings, consecutive positive review count, facilities, pet/parking policies and timezone. Optional fee amounts may be absent in the catalog. Accepts the exact HotelUse hotel_id from a previous result, or hotel_name and destination. A unique, confident match is required. A full hotel name may be used without a destination; add the destination when ambiguous. No stay dates, availability, live prices or room-level offers are included. Supply exactly one hotel_id or hotel_name. Omit unknown optional values; do not send null. Resolve a hotel follow-up by name or position against the most recent relevant ordered search list. Copy its hotel_id exactly; if unavailable, use hotel_name and destination. Ask only if the hotel is ambiguous. For room options or current room prices call get_room_rates directly, passing search_quote_session_id from that search to preserve its stay and preferences. The first get_room_rates response includes all returned room groups and every provider minimum in room_groups. For all room options and prices, use that complete list after one call; do not paginate raw supplier offers or re-query the same stay. The raw_offer_page count describes supplier rate plans, not additional room types. Users can expand room cards locally without another price query. For undated amenities, policies or other hotel facts call get_hotel directly. Do not repeat a destination search before either hotel-specific tool. Existing returned prices may be explained without refreshing when no new search or current quote is requested.

{
  "type": "object",
  "properties": {
    "hotel_id": {
      "type": "string",
      "pattern": "^hu_[a-f0-9]{24}$",
      "description": "Exact HotelUse hotel_id from a previous result."
    },
    "destination": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "City or region to disambiguate the hotel name."
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "region": {
      "type": "string"
    },
    "locale": {
      "type": "string",
      "description": "Traveler BCP 47 language, such as en-GB, independent of the destination."
    },
    "user_locale": {
      "type": "string",
      "minLength": 2,
      "maxLength": 35,
      "description": "Optional traveler locale from client context, such as en-GB. Independent of the hotel destination."
    },
    "user_location_country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "Optional traveler country from client context, used for default currency and residency. Independent of the hotel destination."
    },
    "hotel_name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100,
      "description": "Hotel name when no exact hotel_id is available. A unique, confident match is required. A full hotel name may be used without a destination; add the destination when ambiguous."
    }
  },
  "additionalProperties": false
}