> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentkey.app/llms.txt > Use this file to discover all available pages before exploring further. # travel.hotel.search > Search hotels around a coordinate for given dates and guests. Returns a normalized Hotel page. ## OpenAPI ````yaml api-reference/openapi/v2.yaml POST /v2/ops/travel.hotel.search openapi: 3.1.0 info: description: >- Fixed, versioned, provider-independent methods over AgentKey's upstream catalog. Each method has a stable name, input schema and output schema; the server picks the upstream provider, fails over, normalizes fields and refunds failed attempts. Every response names the provider that served it, the credits charged and every attempt made. title: AgentKey Scenario Methods version: '2' servers: - url: https://api.agentkey.app security: [] paths: /v2/ops/travel.hotel.search: post: tags: - travel summary: >- Search hotels around a coordinate for given dates and guests. Returns a normalized Hotel page. description: >- Hotels available around lat / lon for the check-in / check-out dates, priced for the whole stay in the requested currency. City names and destination ids are not resolved — geocode first; pass radius_km to stay inside a city. Fixed price: 0.3 credits per successful call, whichever provider serves it. operationId: travel_hotel_search requestBody: content: application/json: schema: additionalProperties: false properties: adults: default: 2 description: Number of adult guests. maximum: 30 minimum: 1 type: integer checkin: description: Check-in date, YYYY-MM-DD. type: string checkout: description: Check-out date, YYYY-MM-DD. type: string currency: default: USD description: ISO 4217 currency for prices. type: string cursor: description: >- Opaque pagination cursor from the previous response's next_cursor. Send the same query parameters with it. type: string fields: $ref: '#/components/schemas/FieldsProjection' include_raw: $ref: '#/components/schemas/IncludeRaw' lang: description: Booking language code for names, e.g. en-us, zh-cn. type: string lat: description: Latitude of the search centre, decimal degrees. maximum: 90 minimum: -90 type: number limit: default: 10 description: Maximum number of hotels to return. maximum: 20 minimum: 1 type: integer lon: description: Longitude of the search centre, decimal degrees. maximum: 180 minimum: -180 type: number price_max: description: Maximum total price filter, in the requested currency. type: number price_min: description: Minimum total price filter, in the requested currency. type: number provider: $ref: '#/components/schemas/ProviderShorthand' radius_km: description: >- Search radius around the point, km (the provider default is very wide). type: number rooms: default: 1 description: Number of rooms. maximum: 30 minimum: 1 type: integer routing: $ref: '#/components/schemas/Routing' required: - lat - lon - checkin - checkout type: object required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/HotelPageEnvelope' description: Success envelope '400': $ref: '#/components/responses/ValidationError' '402': $ref: '#/components/responses/InsufficientCredits' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '502': $ref: '#/components/responses/UpstreamFailed' '504': $ref: '#/components/responses/Timeout' security: - ApiKeyAuth: [] components: schemas: FieldsProjection: description: >- Projection: keep only these dotted paths of data, e.g. ["items.id", "items.text"]. items: type: string type: array IncludeRaw: default: false description: >- Attach the raw upstream payload as `raw` (not a stable contract; truncated above 256 KB). type: boolean ProviderShorthand: description: Shorthand for routing.only = [provider]. type: string Routing: additionalProperties: false description: >- Provider routing override. order: try these providers first; only: restrict to these (equivalent to pinning); allow_fallbacks: false tries only the first eligible provider. properties: allow_fallbacks: default: true description: false = try only the first eligible provider. type: boolean only: description: Restrict to these providers. items: type: string type: array order: description: Providers to try first, in order. items: type: string type: array strategy: default: auto description: >- How eligible providers are ordered. auto = the method's curated order. fastest / stable / popular are specified but not implemented yet (400 until then). The price is fixed whatever the strategy; mutually exclusive with order. enum: - auto type: string type: object HotelPageEnvelope: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: $ref: '#/components/schemas/HotelPage' type: object description: Success envelope whose data is a HotelPage. Envelope: description: Success envelope. `data` is the method's output object. properties: attempts: items: $ref: '#/components/schemas/Attempt' type: array credits_charged: description: Credits charged for this call (the method's fixed price). type: number data: description: Method output (typed per method). op: description: Method name. type: string op_version: description: Method version that served the call. type: integer provider: description: Provider that actually served the call. type: string raw: description: Upstream payload, only with include_raw=true. Not a stable contract. raw_truncated: type: boolean request_id: description: Correlation id; quote it in support requests. type: string took_ms: type: integer unsupported_fields: description: >- Output paths this provider structurally does not supply; such fields are null for a different reason than 'missing on this record'. items: type: string type: array required: - op - op_version - provider - request_id - credits_charged - took_ms - attempts - unsupported_fields - data type: object HotelPage: additionalProperties: false description: One page of hotel offers. properties: items: items: $ref: '#/components/schemas/Hotel' type: array next_cursor: description: >- Opaque cursor for the next page; null when exhausted or the provider cannot page. type: - string - 'null' required: - items - next_cursor type: object ErrorEnvelope: properties: attempts: items: $ref: '#/components/schemas/Attempt' type: array code: type: integer error: description: Human-readable message. type: string error_type: description: >- validation | not_found | rate_limit | timeout | insufficient_credits | upstream_unauthorized | upstream_unavailable | provider_error type: string op: description: Method name. type: string request_id: description: Correlation id. type: string required: - error - code - error_type type: object Attempt: description: >- One upstream try. Present on success and failure so a failover is never invisible. properties: error_type: description: >- validation | not_found | rate_limit | timeout | upstream_unauthorized | upstream_unavailable | provider_error type: string provider: description: Provider slug. type: string refunded: description: true when the reservation for this attempt was refunded. type: boolean status: description: HTTP status AgentKey mapped this attempt to (200 on success). type: integer took_ms: type: integer tool: description: Registry tool name (Provider/operation) that was called. type: string upstream_status: description: The provider's real HTTP status; absent when nothing was received. type: integer required: - provider - tool - status - took_ms type: object Hotel: additionalProperties: false description: A hotel offer for the requested dates and guests. properties: address: description: Street address / district as a display string. type: - string - 'null' checkin: description: Earliest check-in time as the hotel states it, HH:MM local. type: - string - 'null' checkout: description: Latest check-out time as the hotel states it, HH:MM local. type: - string - 'null' city: description: City / town name as the provider reports it. type: - string - 'null' country: description: ISO 3166-1 alpha-2 country code. type: - string - 'null' id: description: Provider hotel id (Booking.com hotel_id). type: string lat: description: Latitude in decimal degrees. type: - number - 'null' lon: description: Longitude in decimal degrees. type: - number - 'null' name: description: Hotel name. type: string photo_url: description: Main photo URL. type: - string - 'null' price: description: >- Total price for the whole stay (all requested nights, rooms and guests) in the requested currency. properties: amount: description: Amount in major units. type: - number - 'null' currency: description: ISO 4217 currency code. type: - string - 'null' required: - amount - currency type: object rating: description: Guest review score. properties: count: description: Number of reviews. type: - integer - 'null' score: description: Average review score on the provider's scale (Booking.com 0–10). type: - number - 'null' required: - score - count type: object stars: description: Hotel star class (0 when unrated). type: - integer - 'null' url: description: Hotel page URL on the provider. type: - string - 'null' required: - id - name - url - address - city - country - lat - lon - stars - rating - price - photo_url - checkin - checkout type: object responses: ValidationError: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Validation error (unknown field, bad cursor, bad routing) InsufficientCredits: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Insufficient credits NotFound: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Not found (method, or upstream object) RateLimited: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Rate limited upstream UpstreamFailed: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: All providers failed Timeout: content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Timed out securitySchemes: ApiKeyAuth: description: AgentKey API key (ak_…). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.