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
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"