---
title: "Create a hotel search"
description: "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 supplied)."
---

> Documentation Index
> Fetch the complete documentation index at: https://agents.wego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 supplied). Poll /results for ranked hotels. A hotelId search is the only one getHotelRates accepts.

Operation ID: `createHotelSearch`

## Request body

`application/json`

| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `cityCode` | string | no | pattern `^[A-Z]{3}$` | City code to search. One destination only, see oneOf. |
| `hotelId` | integer | no | 1..9007199254740991 | Search a single hotel by id. One destination only, see oneOf. |
| `lat` | number | no | -90..90 | Latitude. Must be paired with lng. |
| `lng` | number | no | -180..180 | Longitude. Must be paired with lat. |
| `radius` | number | no | 1..50; default `10` | Search radius in km around lat/lng. |
| `checkIn` | string | yes | pattern `^\d{4}-\d{2}-\d{2}$` | Check-in date, YYYY-MM-DD. Not in the past. |
| `checkOut` | string | yes | pattern `^\d{4}-\d{2}-\d{2}$` | Check-out date, YYYY-MM-DD. Must be after checkIn. |
| `adults` | integer | no | 1..9; default `2` | Adults across the search (1-9). Defaults to 2, since a room sleeps two. Note the flight search defaults adults to 1. |
| `children` | integer | no | 0..8; default `0` | Children across the search (0-8). Defaults to 0. |
| `rooms` | integer | no | 1..4; default `1` | Rooms to price (1-4). Defaults to 1; cannot exceed adults. |
| `childrenAges` | integer[] | no | items *..8 | 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 | no | pattern `^[A-Z]{3}$`; default `"USD"` | Pricing currency as a 3-letter ISO 4217 code. Defaults to USD. |
| `locale` | string | no | length 1..35; default `"en"` | Response language tag (e.g. en, ar). Defaults to en. |
| `siteCode` | string | no | pattern `^[A-Z]{2}$` | 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. |


Provide exactly one of: `cityCode`, `hotelId`, `lat` + `lng`.


## Responses

| Status | Description |
|---|---|
| `201` | Search created. |
| `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. |

### `201` body

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


## Example

```bash
CHECK_IN=$(date -u -v+60d +%F 2>/dev/null || date -u -d '+60 days' +%F)
CHECK_OUT=$(date -u -v+67d +%F 2>/dev/null || date -u -d '+67 days' +%F)

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"checkIn":"'"$CHECK_IN"'","checkOut":"'"$CHECK_OUT"'","cityCode":"DXB"}' \
  "https://api.wego.com/v1/hotels/searches"
```

Source: https://agents.wego.com/api/hotels/create-hotel-search/index.mdx