{ "openapi": "3.1.0", "info": { "title": "HotelUse API", "version": "1.0.0", "description": "Hotel search, hotel information and live room prices. API and MCP share one account and balance. Prices: search $0.04/call, rooms $0.06/call, hotel information $0.005/new hotel version. Signup credits are issued once. 60 requests/minute, 10 live price calls/minute, 1 concurrent new requests per account by default. Negotiated accounts can have custom limits. Partial and no-availability results are billed; total provider failures are not. Quote sessions expire after 10 minutes. Idempotency-Key replays remain available for 24 hours." }, "servers": [ { "url": "https://www.hoteluse.dev" } ], "security": [ { "bearerAuth": [] } ], "components": { "schemas": { "StarClassification": { "type": "object", "properties": { "source": { "enum": [ "expedia", "catalog" ] }, "verified": { "type": "boolean" }, "checked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "verified", "checked_at" ], "additionalProperties": true }, "StayDateContext": { "type": "object", "properties": { "basis": { "const": "destination_local" }, "time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "local_dates": { "type": "array", "items": { "type": "object", "properties": { "time_zone": { "type": "string" }, "today": { "type": "string" } }, "required": [ "time_zone", "today" ], "additionalProperties": true } }, "resolved_at": { "type": "string" }, "requested_date_intent": { "enum": [ "tonight" ] } }, "required": [ "basis", "time_zone", "local_dates", "resolved_at" ], "additionalProperties": true }, "GuestReviewScore": { "type": "object", "properties": { "provider": { "type": "string" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "scale": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "review_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "score_out_of_10": { "type": "number" } }, "required": [ "provider", "score", "scale", "review_count" ], "additionalProperties": true }, "HotelPolicies": { "type": "object", "properties": { "pets": { "type": "object", "properties": { "allowed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "fee": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "fee_status": { "type": "string" } }, "required": [], "additionalProperties": true }, "parking": { "type": "object", "properties": { "available": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "charge_type": { "type": "string" }, "fee": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "fee_status": { "type": "string" } }, "required": [], "additionalProperties": true }, "check_in": { "type": "object", "properties": { "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "until": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum_age": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [], "additionalProperties": true }, "check_out": { "type": "object", "properties": { "until": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [], "additionalProperties": true }, "source": { "type": "string" }, "as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [], "additionalProperties": true }, "Money": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": true }, "Price": { "type": "object", "properties": { "base": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxes_and_fees": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pay_at_property": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stay_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "stay_total", "currency" ], "additionalProperties": true }, "Cancellation": { "type": "object", "properties": { "refundable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "free_cancellation_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "free_cancellation_until_local": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "time_basis": { "type": "string" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "penalties": { "type": "array", "items": { "type": "object", "properties": { "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deadline_local": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "until_local": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_parameters": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "required": [], "additionalProperties": true } } }, "required": [], "additionalProperties": true }, "RoomImage": { "type": "object", "properties": { "url": { "type": "string" }, "provider": { "type": "string" }, "external_room_id": { "type": "string" }, "match": { "enum": [ "provider_room_id", "giata_room_group" ] } }, "required": [ "url", "provider", "external_room_id", "match" ], "additionalProperties": true }, "Offer": { "type": "object", "properties": { "quote_basis": { "type": "string" }, "room_allocations": { "type": "array", "items": { "type": "object", "properties": { "room_index": { "type": "integer" }, "adults": { "type": "integer" }, "children_ages": { "type": "array", "items": { "type": "integer" } }, "provider_offer_id": { "type": "string" }, "external_room_id": { "type": "string" }, "stay_total": { "$ref": "#/components/schemas/Money" }, "cancellation": { "$ref": "#/components/schemas/Cancellation" }, "meal_plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_policy": { "anyOf": [ { "type": "object", "properties": {}, "required": [], "additionalProperties": true }, { "type": "null" } ] } }, "required": [], "additionalProperties": true } }, "booking_url": { "type": "string", "format": "uri", "description": "Safe supplier booking link with HotelUse affiliate tracking, when returned by the provider. Retains the quoted itinerary and rate parameters." }, "room_images": { "type": "array", "items": { "$ref": "#/components/schemas/RoomImage" } }, "offer_id": { "type": "string" }, "provider": { "type": "string" }, "hotel_id": { "type": "string" }, "shared_room_group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "room_group_name": { "type": "string" }, "room_mapping_source": { "type": "string" }, "currency": { "type": "string" }, "room_name": { "type": "string" }, "external_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "meal_plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stay_total": { "$ref": "#/components/schemas/Money" }, "price": { "$ref": "#/components/schemas/Price" }, "taxes_and_mandatory_fees_included": { "type": "boolean" }, "cancellation": { "$ref": "#/components/schemas/Cancellation" }, "checked_at": { "type": "string" }, "price_scope": { "type": "string" }, "maximum_occupancy": { "anyOf": [ { "type": "object", "properties": { "adults": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "children": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "from_age": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "to_age": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [], "additionalProperties": true } }, { "type": "integer" }, { "type": "null" } ] }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [], "additionalProperties": true }, { "type": "null" } ] }, "payment_policy": { "anyOf": [ { "type": "object", "properties": {}, "required": [], "additionalProperties": true }, { "type": "null" } ] }, "conditional_charges": { "type": "array", "items": { "type": "object", "properties": {}, "required": [], "additionalProperties": true } }, "price_breakdown": { "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "currency_conversion": { "type": "object", "properties": { "source_currency": { "type": "string" }, "source_prepaid_total": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_stay_total": { "type": "string" }, "source_pay_at_property": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "booking_currency": { "type": "string" }, "target_currency": { "type": "string" }, "exchange_rate": { "type": "number" }, "premium_rate": { "type": "string" }, "effective_rate": { "type": "number" }, "rate_application": { "type": "string" }, "rate_timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "estimated": { "type": "boolean" } }, "required": [], "additionalProperties": true }, "unconfirmed_mandatory_fees": { "type": "array", "items": { "type": "object", "properties": { "provider_charge_id": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "reason": { "type": "string" } }, "required": [], "additionalProperties": true } }, "mandatory_fees": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "original_amount": { "$ref": "#/components/schemas/Money" }, "display_amount": { "$ref": "#/components/schemas/Money" }, "included_in_stay_total": { "type": "boolean" }, "pay_at_property": { "type": "boolean" }, "exchange_rate": { "type": "number" }, "display_is_estimated": { "type": "boolean" } }, "required": [], "additionalProperties": true } } }, "required": [ "offer_id", "provider", "hotel_id", "stay_total", "price", "cancellation" ], "additionalProperties": true }, "SourceRun": { "type": "object", "properties": { "source_id": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "dispatched": { "type": "integer" }, "elapsed_ms": { "type": "integer" }, "queue_ms": { "type": "integer" }, "http_ms": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "timeout_origin": { "type": "string" }, "stage": { "type": "string" }, "http_status": { "type": "integer" }, "upstream_codes": { "type": "array", "items": { "type": "string" } }, "upstream_types": { "type": "array", "items": { "type": "string" } } }, "required": [ "code" ], "additionalProperties": true } } }, "required": [ "source_id", "status", "attempts", "elapsed_ms", "errors" ], "additionalProperties": true }, "ProviderRun": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "planned_requests": { "type": "integer" }, "dispatched_requests": { "type": "integer" }, "unstarted_requests": { "type": "integer" }, "upstream_requests": { "type": "integer" }, "completed_requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "elapsed_ms": { "type": "number" }, "errors": { "type": "array", "items": { "type": "string" } }, "source_results": { "type": "array", "items": { "$ref": "#/components/schemas/SourceRun" } }, "batch_results": { "type": "array", "items": { "$ref": "#/components/schemas/SourceRun" } }, "max_offers_returned": { "type": "integer" } }, "required": [ "provider", "status", "upstream_requests", "completed_requests", "failed_requests" ], "additionalProperties": true }, "ProviderHotelResult": { "type": "object", "properties": { "provider": { "type": "string" }, "status": { "type": "string" }, "lowest_offer": { "anyOf": [ { "$ref": "#/components/schemas/Offer" }, { "type": "null" } ] }, "incomplete": { "type": "boolean" }, "coverage_incomplete": { "type": "boolean" }, "quote_status": { "type": "string" } }, "required": [ "provider", "status", "lowest_offer" ], "additionalProperties": true }, "RoomGroup": { "type": "object", "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/RoomImage" } }, "room_group_id": { "type": "string" }, "shared_room_group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mapping_source": { "type": "string" }, "room_name": { "type": "string" }, "currency": { "type": "string" }, "price_scope": { "type": "string" }, "lowest_offer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lowest_stay_total": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "offer_ids": { "type": "array", "items": { "type": "string" } }, "provider_prices": { "type": "array", "items": { "type": "object", "properties": { "booking_url": { "type": "string", "format": "uri", "description": "Affiliate-tracked supplier link for this provider minimum, when available." }, "provider": { "type": "string" }, "lowest_offer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lowest_stay_total": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "offer_ids": { "type": "array", "items": { "type": "string" } } }, "required": [], "additionalProperties": true } } }, "required": [ "room_group_id", "mapping_source", "provider_prices", "offer_ids" ], "additionalProperties": true }, "HotelRates": { "type": "object", "properties": { "hotel_id": { "type": "string" }, "availability_status": { "type": "string" }, "status": { "type": "string" }, "lowest_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_results": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderHotelResult" } }, "hotel": { "$ref": "#/components/schemas/HotelSummary" } }, "required": [ "hotel_id", "status", "lowest_provider", "provider_results" ], "additionalProperties": true }, "HotelSummary": { "type": "object", "properties": { "review_scores": { "type": "array", "items": { "$ref": "#/components/schemas/GuestReviewScore" } }, "review_summary": { "anyOf": [ { "$ref": "#/components/schemas/GuestReviewScore" }, { "type": "null" } ] }, "consecutive_positive_review_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "policies": { "$ref": "#/components/schemas/HotelPolicies" }, "catalog_identity": { "type": "object", "properties": { "basis": { "enum": [ "giata_and_provider_identity", "exact_provider_identity" ] }, "source_hotel_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "basis", "source_hotel_ids" ], "additionalProperties": true }, "hotel_id": { "type": "string" }, "name": { "type": "string" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "star_rating": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "star_classification": { "$ref": "#/components/schemas/StarClassification" }, "geo": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [], "additionalProperties": true }, "property_type": { "type": "string" }, "image": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string" }, "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "hotel_id", "name" ], "additionalProperties": true }, "HotelRecord": { "type": "object", "properties": { "review_scores": { "type": "array", "items": { "$ref": "#/components/schemas/GuestReviewScore" } }, "review_summary": { "anyOf": [ { "$ref": "#/components/schemas/GuestReviewScore" }, { "type": "null" } ] }, "consecutive_positive_review_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "policies": { "$ref": "#/components/schemas/HotelPolicies" }, "hotel_id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } }, "required": [], "additionalProperties": true }, "giata_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "star_rating": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "star_classification": { "$ref": "#/components/schemas/StarClassification" }, "geo": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [], "additionalProperties": true }, "property_type": { "type": "string" }, "amenities": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [], "additionalProperties": true } }, "provider_records": { "type": "array", "items": { "type": "object", "properties": { "connection": { "type": "string" }, "provider": { "type": "string" }, "external_hotel_id": { "type": "string" } }, "required": [ "connection", "provider", "external_hotel_id" ], "additionalProperties": true } }, "source_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "record_version": { "type": "string" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptions": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "content": { "type": "string" } }, "required": [], "additionalProperties": true } } }, "required": [ "hotel_id", "name", "provider_records", "record_version" ], "additionalProperties": true }, "GeographicScope": { "type": "object", "properties": { "source": { "type": "string" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "center": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "required": [], "additionalProperties": true }, "time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "radius_km": { "type": "number" }, "address_city": { "type": "string" }, "country": { "type": "string" }, "catalog_index": { "type": "object", "properties": { "refreshed_at": { "type": "string" }, "refresh_interval_seconds": { "type": "integer" }, "max_age_seconds": { "type": "integer" } }, "required": [], "additionalProperties": true } }, "required": [], "additionalProperties": true }, "Coverage": { "type": "object", "properties": { "matching_hotels": { "type": "integer" }, "matching_hotels_is_lower_bound": { "type": "boolean" }, "priced_hotels": { "type": "integer" }, "available_hotels": { "type": "integer" }, "unmapped_hotels": { "type": "integer" }, "complete": { "type": "boolean" }, "service_limit_reached": { "type": "boolean" }, "ranking_scope": { "type": "string" } }, "required": [], "additionalProperties": true }, "Usage": { "type": "object", "properties": { "hotel_record_units": { "type": "integer" }, "search_calls": { "type": "integer" }, "room_calls": { "type": "integer" }, "trial_units_used": { "type": "integer" }, "paid_units": { "type": "integer" }, "paid_usd": { "type": "string" }, "unit_price_usd": { "type": "string" }, "billing_receipt_id": { "type": "string" }, "replayed": { "type": "boolean" } }, "required": [ "hotel_record_units", "search_calls", "room_calls", "paid_usd" ], "additionalProperties": true }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "credits_charged": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "code", "message", "credits_charged" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": true }, "search_hotels_response": { "type": "object", "properties": { "schema_version": { "const": "1.0" }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "context": { "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "date_context": { "$ref": "#/components/schemas/StayDateContext" }, "quote_session_id": { "type": "string" }, "search_session_id": { "type": "string" }, "provider_results": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderRun" } }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "geographic_scope": { "$ref": "#/components/schemas/GeographicScope" }, "ranking": { "type": "object", "properties": { "sort": { "type": "string" }, "distance_bucket_meters": { "type": "number" }, "unpriced_hotels": { "type": "string" }, "fallback_reason": { "type": "string" }, "price_advantage_basis": { "type": "string" }, "unknown_advantage": { "type": "string" } }, "required": [], "additionalProperties": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "hotel": { "$ref": "#/components/schemas/HotelSummary" }, "rates": { "$ref": "#/components/schemas/HotelRates" }, "distance_meters": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "distance_bucket": { "anyOf": [ { "type": "object", "properties": { "from_m": { "type": "number" }, "to_m": { "type": "number" } }, "required": [], "additionalProperties": true }, { "type": "null" } ] }, "brek_price_advantage": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" }, "compared_provider": { "type": "string" } }, "required": [], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "hotel", "rates" ], "additionalProperties": true } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reuse_until": { "type": "string" }, "timings": { "type": "object", "properties": { "catalog_ms": { "type": "number" }, "quotes_ms": { "type": "number" }, "room_grouping_ms": { "type": "number" }, "total_ms": { "type": "number" } }, "required": [], "additionalProperties": true }, "catalog_quality": { "type": "object", "properties": { "identity_verification": { "type": "string" }, "duplicate_records_collapsed": { "type": "integer" }, "inactive_duplicate_mappings_ignored": { "type": "integer" }, "star_classification": { "type": "string" }, "unverified_hotels": { "type": "integer" }, "regional_unverified_records": { "type": "integer" }, "failed_metadata_batches": { "type": "integer" }, "matching_hotels_is_lower_bound": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "results", "coverage", "provider_results", "quote_session_id", "next_cursor" ], "additionalProperties": true }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "schema_version", "request_id", "data", "usage" ], "additionalProperties": true }, "get_hotel_response": { "type": "object", "properties": { "schema_version": { "const": "1.0" }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "hotel": { "$ref": "#/components/schemas/HotelRecord" } }, "required": [ "hotel" ], "additionalProperties": true }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "schema_version", "request_id", "data", "usage" ], "additionalProperties": true }, "get_room_rates_response": { "type": "object", "properties": { "schema_version": { "const": "1.0" }, "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "context": { "type": "object", "properties": {}, "required": [], "additionalProperties": true }, "date_context": { "$ref": "#/components/schemas/StayDateContext" }, "quote_session_id": { "type": "string" }, "hotel_id": { "type": "string" }, "hotel": { "$ref": "#/components/schemas/HotelSummary" }, "provider_results": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderRun" } }, "returned_offer_count": { "type": "integer" }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "room_groups": { "type": "array", "items": { "$ref": "#/components/schemas/RoomGroup" } }, "room_grouping": { "type": "object", "properties": { "source": { "type": "string" }, "status": { "type": "string" }, "mapped_offers": { "type": "integer" }, "total_offers": { "type": "integer" }, "scope": { "type": "string" } }, "required": [], "additionalProperties": true }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reuse_until": { "type": "string" }, "offer_limit_reached": { "type": "boolean" }, "timings": { "type": "object", "properties": { "catalog_ms": { "type": "number" }, "quotes_ms": { "type": "number" }, "room_grouping_ms": { "type": "number" }, "total_ms": { "type": "number" } }, "required": [], "additionalProperties": true }, "catalog_quality": { "type": "object", "properties": { "identity_verification": { "type": "string" }, "duplicate_records_collapsed": { "type": "integer" }, "inactive_duplicate_mappings_ignored": { "type": "integer" }, "star_classification": { "type": "string" }, "unverified_hotels": { "type": "integer" }, "regional_unverified_records": { "type": "integer" }, "failed_metadata_batches": { "type": "integer" }, "matching_hotels_is_lower_bound": { "type": "boolean" } }, "required": [], "additionalProperties": true } }, "required": [ "hotel_id", "offers", "returned_offer_count", "provider_results", "quote_session_id", "next_cursor" ], "additionalProperties": true }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "schema_version", "request_id", "data", "usage" ], "additionalProperties": true } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Account API key from the HotelUse dashboard." } } }, "paths": { "/v1/hotels/search": { "post": { "operationId": "search_hotels", "summary": "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.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 }, "description": "Reuse for retries of the same operation and body. A different body with the same key returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "properties": { "location": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "city": { "type": "string" }, "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." } }, "required": [ "country" ], "additionalProperties": false, "anyOf": [ { "not": { "anyOf": [ { "required": [ "latitude" ] }, { "required": [ "longitude" ] } ] } }, { "required": [ "latitude", "longitude" ] } ], "allOf": [ { "anyOf": [ { "required": [ "city" ] }, { "required": [ "latitude", "longitude" ] } ] } ] }, "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 }, "context": { "type": "object", "properties": { "check_in": { "type": "string", "format": "date", "description": "Hotel-local calendar date. Today is allowed in the destination time zone, even if UTC is already tomorrow." }, "check_out": { "type": "string", "format": "date" }, "date_intent": { "type": "string", "enum": [ "tonight" ], "description": "Resolve tonight as one night using the destination/hotel local date on the server. Omit check_in and check_out when using this field." }, "device": { "type": "string", "enum": [ "desktop", "mobile_web", "mobile_app" ], "default": "desktop", "description": "Actual traveler booking channel. Native-app rates require an approved app integration. Keep unchanged across search, rooms and booking." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "USD" }, "locale": { "type": "string", "maxLength": 35, "description": "BCP 47 language tag; provider content can fall back to its source language." }, "time_zone": { "type": "string", "maxLength": 80, "description": "Optional IANA traveler time zone, not used to decide whether a hotel-local check-in is in the past. The server resolves the destination/property time zone." }, "market": { "type": "object", "properties": { "residency_country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "residency_country" ], "additionalProperties": false }, "rooms": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 8 }, "children_ages": { "type": "array", "maxItems": 6, "items": { "type": "integer", "minimum": 0, "maximum": 17 } } }, "required": [ "adults", "children_ages" ], "additionalProperties": false } } }, "required": [ "rooms" ], "additionalProperties": false, "oneOf": [ { "required": [ "check_in", "check_out" ], "not": { "required": [ "date_intent" ] } }, { "required": [ "date_intent" ], "not": { "anyOf": [ { "required": [ "check_in" ] }, { "required": [ "check_out" ] } ] } } ] }, "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 }, "providers": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "enum": [ "expedia", "booking", "agoda", "brek", "trip", "vio" ] } }, "page_size": { "type": "integer", "minimum": 1, "maximum": 200 }, "billing": { "type": "object", "properties": { "max_units": { "type": "integer", "minimum": 0 } }, "required": [ "max_units" ], "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." } }, "required": [ "location", "context" ], "additionalProperties": false }, { "type": "object", "properties": { "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." } }, "required": [ "quote_session_id" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Result envelope with data, request_id and usage receipt. A partial result explicitly reports coverage and provider errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_hotels_response" } } } }, "400": { "description": "Invalid input; no charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits or caller budget exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Cumulative hotel download access limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Hotel or quote session not found or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency key conflict or uncommitted quote expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No provider mapping supports this hotel, or the requested providers cannot quote the dates/occupancy; no charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account limit reached; respect Retry-After. No charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No upstream provider completed; no charge. If billing_confirmation_pending, retry with the same Idempotency-Key to recover the outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Catalog deadline exceeded; no charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/hotels/get": { "post": { "operationId": "get_hotel", "summary": "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.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 }, "description": "Reuse for retries of the same operation and body. A different body with the same key returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hotel_id": { "type": "string" }, "billing": { "type": "object", "properties": { "max_units": { "type": "integer", "minimum": 0 } }, "required": [ "max_units" ], "additionalProperties": false }, "include": { "type": "array", "items": { "enum": [ "provider_records", "provenance" ] } } }, "required": [ "hotel_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Result envelope with data, request_id and usage receipt. A partial result explicitly reports coverage and provider errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_hotel_response" } } } }, "400": { "description": "Invalid input; no charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits or caller budget exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Cumulative hotel download access limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Hotel or quote session not found or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency key conflict or uncommitted quote expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No provider mapping supports this hotel, or the requested providers cannot quote the dates/occupancy; no charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account limit reached; respect Retry-After. No charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No upstream provider completed; no charge. If billing_confirmation_pending, retry with the same Idempotency-Key to recover the outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Catalog deadline exceeded; no charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rates/rooms": { "post": { "operationId": "get_room_rates", "summary": "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.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 }, "description": "Reuse for retries of the same operation and body. A different body with the same key returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "properties": { "hotel_id": { "type": "string" }, "context": { "type": "object", "properties": { "check_in": { "type": "string", "format": "date", "description": "Hotel-local calendar date. Today is allowed in the destination time zone, even if UTC is already tomorrow." }, "check_out": { "type": "string", "format": "date" }, "date_intent": { "type": "string", "enum": [ "tonight" ], "description": "Resolve tonight as one night using the destination/hotel local date on the server. Omit check_in and check_out when using this field." }, "device": { "type": "string", "enum": [ "desktop", "mobile_web", "mobile_app" ], "default": "desktop", "description": "Actual traveler booking channel. Native-app rates require an approved app integration. Keep unchanged across search, rooms and booking." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "USD" }, "locale": { "type": "string", "maxLength": 35, "description": "BCP 47 language tag; provider content can fall back to its source language." }, "time_zone": { "type": "string", "maxLength": 80, "description": "Optional IANA traveler time zone, not used to decide whether a hotel-local check-in is in the past. The server resolves the destination/property time zone." }, "market": { "type": "object", "properties": { "residency_country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "residency_country" ], "additionalProperties": false }, "rooms": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 8 }, "children_ages": { "type": "array", "maxItems": 6, "items": { "type": "integer", "minimum": 0, "maximum": 17 } } }, "required": [ "adults", "children_ages" ], "additionalProperties": false } } }, "required": [ "rooms" ], "additionalProperties": false, "oneOf": [ { "required": [ "check_in", "check_out" ], "not": { "required": [ "date_intent" ] } }, { "required": [ "date_intent" ], "not": { "anyOf": [ { "required": [ "check_in" ] }, { "required": [ "check_out" ] } ] } } ] }, "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 }, "providers": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "enum": [ "expedia", "booking", "agoda", "brek", "trip", "vio" ] } }, "page_size": { "type": "integer", "minimum": 1, "maximum": 200 }, "billing": { "type": "object", "properties": { "max_units": { "type": "integer", "minimum": 0 } }, "required": [ "max_units" ], "additionalProperties": false } }, "required": [ "hotel_id", "context" ], "additionalProperties": false }, { "type": "object", "properties": { "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." } }, "required": [ "quote_session_id" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Result envelope with data, request_id and usage receipt. A partial result explicitly reports coverage and provider errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_room_rates_response" } } } }, "400": { "description": "Invalid input; no charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits or caller budget exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Cumulative hotel download access limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Hotel or quote session not found or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency key conflict or uncommitted quote expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No provider mapping supports this hotel, or the requested providers cannot quote the dates/occupancy; no charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account limit reached; respect Retry-After. No charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "No upstream provider completed; no charge. If billing_confirmation_pending, retry with the same Idempotency-Key to recover the outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Catalog deadline exceeded; no charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }