GET /v1/places
Resolves a free-text location query to canonical Wego places (cities, airports, states, districts, hotels) with codes and coordinates, for use in later flight and hotel searches. When metadata.hasAmbiguity is true, clarify with the user before proceeding.
Operation ID: getPlaces
Parameters
| Name | In | Type | Required | Constraints | Description |
|---|---|---|---|---|---|
query |
query | string | yes | length 1..100 | Free text to resolve to typed places with codes. A place-name search (city, airport, district, hotel). |
types |
query | city | airport | state | district | hotel[] |
no | items 1..*; each of city, airport, state, district, hotel |
Place types to resolve; repeat or comma-separate to mix. |
locale |
query | string | no | length 1..35 | Language tag for localized place names (e.g. en, ar). Omitted, the search is language-neutral: the query matches names in any language (sent upstream as the locale wildcard) and results carry canonical English names. Pass a tag to localize the returned names instead. getNearbyPlaces, by contrast, defaults to en. |
page |
query | integer | no | 1..100; default 1 |
Page number, 1-based (max 100). Defaults to 1. |
pageSize |
query | integer | no | 1..50; default 10 |
Results per page (1-50). Defaults to 10. |
Responses
| Status | Description |
|---|---|
200 |
Matching places plus pagination/ambiguity metadata. |
400 |
Invalid query parameters. |
401 |
Missing or invalid bearer token. |
429 |
Rate limit exceeded; retry after the Retry-After seconds. |
502 |
The upstream places service returned an invalid response. |
503 |
The places service is temporarily unavailable; retry after the Retry-After seconds. |
200 body
| Field | Type | Always present | Description |
|---|---|---|---|
results |
object[] | yes | The matched places for this page. |
↳ id |
number | string | no | Opaque identifier, unique per place. Do not send it to other endpoints or build wego.com URLs from it: reference a place by code, or by cityCode for a hotels search. |
↳ code |
string | no | IATA-style code (airport/city), when the place has one. |
↳ name |
string | yes | Display name of the place. |
↳ type |
string | yes | Place kind: city, airport, state, district or hotel. |
↳ cityCode |
string | no | Code of the city this place belongs to. |
↳ latitude |
number | no | Latitude in decimal degrees, when known. |
↳ longitude |
number | no | Longitude in decimal degrees, when known. |
metadata |
object | yes | Pagination and ambiguity signals for this place search. |
↳ resultCount |
integer | yes | Number of results on the current page (always <= pageSize). |
↳ totalCandidates |
integer | yes | Total matches held for this query (post-dedup, pre-pagination) – the ceiling pagination can reach. 0 means no matches; an empty deep page with totalCandidates > 0 just means the offset is past the end. |
↳ hasMore |
boolean | yes | True when a further page exists. |
↳ hasAmbiguity |
boolean | yes | True when several distinct real-world locations share the query; ask the user to disambiguate before searching. |
↳ disambiguationHint |
string | no | Short clarification sample, present only when hasAmbiguity. |
Example
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.wego.com/v1/places?query=dubai"