---
title: "Create a hotel search"
method: POST
path: "/v1/hotels/searches"
tags: ["Hotels"]
---

# Create a hotel search

`POST /v1/hotels/searches`

Creates a Book-on-Wego hotel search (city, single hotel, or geo point) and returns its opaque searchId plus the occupancy priced upstream (resolved child ages, incl. the age-8 fallback when none were supplied). Poll /results for ranked hotels.

## Request body

- union
  - object
    - `cityCode` string, required — City code to search. One destination only, see oneOf.
    - `hotelId` integer — Search a single hotel by id. One destination only, see oneOf.
    - `lat` number — Latitude. Must be paired with lng.
    - `lng` number — Longitude. Must be paired with lat.
    - `radius` number — Search radius in km around lat/lng.
    - `checkIn` string, required — Check-in date, YYYY-MM-DD. Not in the past.
    - `checkOut` string, required — Check-out date, YYYY-MM-DD. Must be after checkIn.
    - `adults` integer — Adults across the search (1-9). Defaults to 2, since a room sleeps two. Note the flight search defaults adults to 1.
    - `children` integer — Children across the search (0-8). Defaults to 0.
    - `rooms` integer — Rooms to price (1-4). Defaults to 1; cannot exceed adults.
    - `childrenAges` integer[] — Per-child ages (integers 0–17). When provided, the count must equal `children`. When omitted, each child is priced at age 8 (the documented fallback).
    - `currency` string — Pricing currency as a 3-letter ISO 4217 code. Defaults to USD.
    - `locale` string — Response language tag (e.g. en, ar). Defaults to en.
    - `siteCode` string — Wego market (point of sale) as a 2-letter code, e.g. AE. Optional: if omitted the API defaults to US. A client that knows the user's market (the wego CLI derives it from the id_token) passes it as an explicit siteCode.
  - object
    - `cityCode` string — City code to search. One destination only, see oneOf.
    - `hotelId` integer, required — Search a single hotel by id. One destination only, see oneOf.
    - `lat` number — Latitude. Must be paired with lng.
    - `lng` number — Longitude. Must be paired with lat.
    - `radius` number — Search radius in km around lat/lng.
    - `checkIn` string, required — Check-in date, YYYY-MM-DD. Not in the past.
    - `checkOut` string, required — Check-out date, YYYY-MM-DD. Must be after checkIn.
    - `adults` integer — Adults across the search (1-9). Defaults to 2, since a room sleeps two. Note the flight search defaults adults to 1.
    - `children` integer — Children across the search (0-8). Defaults to 0.
    - `rooms` integer — Rooms to price (1-4). Defaults to 1; cannot exceed adults.
    - `childrenAges` integer[] — Per-child ages (integers 0–17). When provided, the count must equal `children`. When omitted, each child is priced at age 8 (the documented fallback).
    - `currency` string — Pricing currency as a 3-letter ISO 4217 code. Defaults to USD.
    - `locale` string — Response language tag (e.g. en, ar). Defaults to en.
    - `siteCode` string — Wego market (point of sale) as a 2-letter code, e.g. AE. Optional: if omitted the API defaults to US. A client that knows the user's market (the wego CLI derives it from the id_token) passes it as an explicit siteCode.
  - object
    - `cityCode` string — City code to search. One destination only, see oneOf.
    - `hotelId` integer — Search a single hotel by id. One destination only, see oneOf.
    - `lat` number, required — Latitude. Must be paired with lng.
    - `lng` number, required — Longitude. Must be paired with lat.
    - `radius` number — Search radius in km around lat/lng.
    - `checkIn` string, required — Check-in date, YYYY-MM-DD. Not in the past.
    - `checkOut` string, required — Check-out date, YYYY-MM-DD. Must be after checkIn.
    - `adults` integer — Adults across the search (1-9). Defaults to 2, since a room sleeps two. Note the flight search defaults adults to 1.
    - `children` integer — Children across the search (0-8). Defaults to 0.
    - `rooms` integer — Rooms to price (1-4). Defaults to 1; cannot exceed adults.
    - `childrenAges` integer[] — Per-child ages (integers 0–17). When provided, the count must equal `children`. When omitted, each child is priced at age 8 (the documented fallback).
    - `currency` string — Pricing currency as a 3-letter ISO 4217 code. Defaults to USD.
    - `locale` string — Response language tag (e.g. en, ar). Defaults to en.
    - `siteCode` string — Wego market (point of sale) as a 2-letter code, e.g. AE. Optional: if omitted the API defaults to US. A client that knows the user's market (the wego CLI derives it from the id_token) passes it as an explicit siteCode.

## Response `201`

Search created.

- object
  - `searchId` string, required — Opaque id for the created search.
  - `occupancy` object, required — The occupancy priced upstream for this search (ages resolved, incl. fallback).
    - `adults` integer, required — Adults priced upstream for this search.
    - `childrenAges` integer[], required — Resolved per-child ages actually sent upstream (age-8 fallback when omitted).
    - `rooms` integer, required — Rooms priced upstream for this search.
  - `siteCode` string, required — The site code (Wego market) the search was created for.
  - `siteCodeSource` 'explicit' | 'default', required — How the API resolved siteCode: explicit (caller-supplied – including a market a client derived and passed) or default (US, no site supplied).

## Other responses

- `400` — Invalid request parameters.
- `401` — Missing or invalid bearer token.
- `404` — Unknown hotel.
- `429` — Rate limit exceeded; retry after the `Retry-After` seconds.
- `502` — The upstream hotels service returned an invalid response.
- `503` — The hotels service is unavailable (`upstream_unavailable`) or rate-limited upstream (`upstream_rate_limited`); retry after the `Retry-After` seconds.

---

[API](https://skmtc.net/wego/apis/wego-api.md) · [All operations](https://skmtc.net/wego/apis/wego-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/wego/wego-api/revisions/e5d7af502419/schema)