---
title: "Search hotels around a coordinate for given dates and guests. Returns a normalized Hotel page."
method: POST
path: "/v2/ops/travel.hotel.search"
tags: ["travel"]
---

# Search hotels around a coordinate for given dates and guests. Returns a normalized Hotel page.

`POST /v2/ops/travel.hotel.search`

## Request

- Base URL: `https://api.agentkey.app`
- URL: `https://api.agentkey.app/v2/ops/travel.hotel.search`
- Auth: HTTP bearer

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.

## Request body

- object
  - `adults` integer: Number of adult guests.
  - `checkin` string, required: Check-in date, YYYY-MM-DD.
  - `checkout` string, required: Check-out date, YYYY-MM-DD.
  - `currency` string: ISO 4217 currency for prices.
  - `cursor` string: Opaque pagination cursor from the previous response's next_cursor. Send the same query parameters with it.
  - `fields` string[]: Projection: keep only these dotted paths of data, e.g. ["items.id", "items.text"].
  - `include_raw` boolean: Attach the raw upstream payload as `raw` (not a stable contract; truncated above 256 KB).
  - `lang` string: Booking language code for names, e.g. en-us, zh-cn.
  - `lat` number, required: Latitude of the search centre, decimal degrees.
  - `limit` integer: Maximum number of hotels to return.
  - `lon` number, required: Longitude of the search centre, decimal degrees.
  - `price_max` number: Maximum total price filter, in the requested currency.
  - `price_min` number: Minimum total price filter, in the requested currency.
  - `provider` string: Shorthand for routing.only = [provider].
  - `radius_km` number: Search radius around the point, km (the provider default is very wide).
  - `rooms` integer: Number of rooms.
  - `routing` Routing: Provider routing override. order: try these providers first; only: restrict to these (equivalent to pinning); allow_fallbacks: false tries only the first eligible provider.
    - `allow_fallbacks` boolean: false = try only the first eligible provider.
    - `only` string[]: Restrict to these providers.
    - `order` string[]: Providers to try first, in order.
    - `strategy` 'auto': 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.

## Response `200`

Success envelope

- HotelPageEnvelope: Success envelope whose data is a HotelPage.
  - `attempts` Attempt[], required
    - `error_type` string: validation | not_found | rate_limit | timeout | upstream_unauthorized | upstream_unavailable | provider_error
    - `provider` string, required: Provider slug.
    - `refunded` boolean: true when the reservation for this attempt was refunded.
    - `status` integer, required: HTTP status AgentKey mapped this attempt to (200 on success).
    - `took_ms` integer, required
    - `tool` string, required: Registry tool name (Provider/operation) that was called.
    - `upstream_status` integer: The provider's real HTTP status; absent when nothing was received.
  - `credits_charged` number, required: Credits charged for this call (the method's fixed price).
  - `data` object, required: One page of hotel offers.
    - `items` Hotel[], required
      - `address` string, nullable, required: Street address / district as a display string.
      - `checkin` string, nullable, required: Earliest check-in time as the hotel states it, HH:MM local.
      - `checkout` string, nullable, required: Latest check-out time as the hotel states it, HH:MM local.
      - `city` string, nullable, required: City / town name as the provider reports it.
      - `country` string, nullable, required: ISO 3166-1 alpha-2 country code.
      - `id` string, required: Provider hotel id (Booking.com hotel_id).
      - `lat` number, nullable, required: Latitude in decimal degrees.
      - `lon` number, nullable, required: Longitude in decimal degrees.
      - `name` string, required: Hotel name.
      - `photo_url` string, nullable, required: Main photo URL.
      - `price` object, required: Total price for the whole stay (all requested nights, rooms and guests) in the requested currency.
        - `amount` number, nullable, required: Amount in major units.
        - `currency` string, nullable, required: ISO 4217 currency code.
      - `rating` object, required: Guest review score.
        - `count` integer, nullable, required: Number of reviews.
        - `score` number, nullable, required: Average review score on the provider's scale (Booking.com 0–10).
      - `stars` integer, nullable, required: Hotel star class (0 when unrated).
      - `url` string, nullable, required: Hotel page URL on the provider.
    - `next_cursor` string, nullable, required: Opaque cursor for the next page; null when exhausted or the provider cannot page.
  - `op` string, required: Method name.
  - `op_version` integer, required: Method version that served the call.
  - `provider` string, required: Provider that actually served the call.
  - `raw` unknown
  - `raw_truncated` boolean
  - `request_id` string, required: Correlation id; quote it in support requests.
  - `took_ms` integer, required
  - `unsupported_fields` string[], required: Output paths this provider structurally does not supply; such fields are null for a different reason than 'missing on this record'.

## Other responses

- `400`: Validation error (unknown field, bad cursor, bad routing)
- `402`: Insufficient credits
- `404`: Not found (method, or upstream object)
- `429`: Rate limited upstream
- `502`: All providers failed
- `504`: Timed out

---

[API](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods.md) - [All operations](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/llms.txt) - [OpenAPI document](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/revisions/a7cf5b682fdd?raw)