About this endpoint
Finds places by name.
Finds up to 50 cities and populated places whose name starts with q in any stored language, ignoring accents and capitalization, sorted by population from the largest. Includes an optional country filter. The results contain the known names in the country official languages. if lang language is specified - it returns known additional translations in up to 2 languages.
Query Parameter(s)
| Attribute | Type | Mandatory | Description |
|---|---|---|---|
| q | String | Yes | The text to search for, 1-200 characters after trimming whitespace. Matched against every stored name of a place (case-insensitive, accent-insensitive), as a prefix. |
| country | String | No | Restricts results to this ISO 3166-1 alpha-2 country code (case-insensitive). An unrecognized but well-formed code simply yields no results. |
| limit | Integer | No | The maximum number of results to return (default 10, at most 50). |
| lang | String | No | Return additional translations for up to 2 languages: comma-separated 2-letter ISO 639-1 codes. Supported: ar, be, bg, cs, da, de, el, en, es, et, fi, fr, hi, hr, hu, is, it, ja, lt, lv, nl, no, pl, pt, ro, ru, sk, sl, sq, sr, sv, sw, uk, zh. Other codes (including 3-letter codes) are ignored and return no translation. |
Response
Returns a JSON object listing up to 50 cities and populated places whose name starts with q in any stored language, sorted by population descending (unknown population last) and capped at limit, along with the data source(s) behind those results.
| Attribute | Type | Mandatory | Description |
|---|---|---|---|
| query | String | Yes | The (trimmed) search text that was searched for. |
| count | Integer | Yes | The number of entries in results (already capped by limit). |
| results | Object Array | Yes | Every place whose name matches the search, sorted by population descending. Empty if none could be found. |
| results[].geonameId | Integer | No | The place GeoNames identifier, or null for a place with no GeoNames data at all. |
| results[].wikidataId | String | No | The place Wikidata entity ID (e.g. Q2807), or null when none is known. |
| results[].nationalId | String | No | The place code in its own country official place register, or null when not known. |
| results[].name | String | Yes | The place's default display name. |
| results[].officialNames | Object Array | Yes | The place's name in every official language of its country (if known). Empty if none are known. Each item has language and name. |
| results[].officialNames[].language | String | Yes | The language's ISO 639-1 code. |
| results[].officialNames[].name | String | Yes | The place's name in that language. |
| results[].translations | Object Array | No | Present only when lang was supplied: the place name in each of the requested languages (if known), in the same order as lang. |
| results[].latitude | Number | Yes | The place latitude. |
| results[].longitude | Number | Yes | The place longitude. |
| results[].countryCode | String | Yes | ISO 3166-1 alpha-2 country code. |
| results[].country | String | No | The country display name, or null if unknown. |
| results[].region | String | No | The place top-level administrative division (e.g. a state or province), or null if unknown. |
| results[].population | Integer | No | The place population, or null if unknown. |
| results[].areaKm2 | Number | No | The place area in square kilometers, or null if unknown. |
| results[].timezone | String | No | The place IANA time zone identifier, or null if unknown. |
| results[].type | Object | No | The place GeoNames type, or null for a place with no GeoNames data at all. |
| results[].type.code | String | Yes | The place GeoNames feature code, e.g. PPLC. |
| results[].type.label | String | No | The human-readable label for code, or null for an unrecognized code. |
| results[].sources | String Array | Yes | The source code(s) that contributed data to this place (e.g. geonames). |
| sources | Object Array | Yes | The dictionary entry for data sources used in results. |
| sources[].id | String | Yes | The source identifier used in results[].sources. |
| sources[].name | String | Yes | The source human-readable display name. |
| sources[].license | String | Yes | The source data license. |
| sources[].attribution | String | No | Custom attribution text this source requires callers to display verbatim, beyond the license itself, or null when there is no such requirement. |
| sources[].updatedAt | String | Yes | The date this source's data was last (re-)imported into the database as a whole, formatted as YYYY-MM-DD. |
Notes
- At most 50 results are returned per call; use
limitto control how many.
- Language codes must be 2-letter ISO 639-1 codes. 3-letter codes are not supported.
- Supported languages (34): Arabic (ar), Belarusian (be), Bulgarian (bg), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Estonian (et), Finnish (fi), French (fr), German (de), Greek (el), Hindi (hi), Hungarian (hu), Icelandic (is), Italian (it), Japanese (ja), Latvian (lv), Lithuanian (lt), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Serbian (sr), Slovak (sk), Slovenian (sl), Spanish (es), Swahili (sw), Swedish (sv), Albanian (sq), Ukrainian (uk), Chinese (zh).
- Sending an unsupported code does not return an error. The request succeeds and
translationsis empty. - A translation is returned only if the upstream source has a name for that place in that language. * The API recognizes 30+ languages, and the coverage may increase over time. Sending the code of the unsupported language does not result in error - you will simply not get a translation for it in the response.
- The API returns the official name or translation in the given language only if the upstream source defines such a name.
officialNameslists place names in the recognized country official languages at the national level (or best-effort guess for certain countries that do not have an official language or it is ambiguous). To return known names in languages recognized at the regional level, uselangfilter.
