GET /v1/places
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"