Search GeoNames places
geonames_search_placesRead-onlyIdempotent
Search the GeoNames gazetteer of 13M+ places by name and filters: country, admin division by its GeoNames code (adminCode1 TX with countries US for Texas), feature class (P populated places, A admin divisions, T mountains and terrain, H water, S buildings and spots), feature code (PPLC capitals, ADM1 states, MT mountains, AIRP airports), population tier, and bounding box. Results carry the geonameId that geonames_get_place, geonames_get_hierarchy, and geonames_get_children take. The default match requires a query term in the place name while letting other terms match the country or admin names ("Berlin, Germany"). Costs 1 GeoNames credit per call.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "geonames_search_places"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entries to return, 1 to 1,000. This tool returns at most 100 per call: a larger limit is held to 100, and the notice says so when more entries remain. Default 10. | |
| match | No | How query is matched. name_required (the default) needs at least one query term in the place name while other terms may match the country or admin names; any_field lets every term match any of those fields; exact_name matches the whole name exactly, alternate and historical names included; name_prefix matches names that start with query. Needs query. | |
| query | No | Place name to search for, such as Springfield or "Berlin, Germany", up to 200 characters. match sets how it is compared. Omit it to search by filters alone, which then needs at least one of countries, featureClasses, featureCodes, or boundingBox (cities alone is not enough). | |
| cities | No | Keep only populated places (class P) with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. A city's sections (PPLX) with their own population pass too. Beside featureClasses or featureCodes, list only class P or class-P codes such as PPLC. | |
| offset | No | Entries to skip before the first one returned, for paging, 0 to 5000. Default 0. | |
| orderBy | No | Result order: relevance or population, largest first. Omit it for GeoNames' own order, which matches relevance except with match name_prefix. | |
| countries | No | ISO 3166-1 country codes, up to 10, as a list: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. UK is accepted for GB and FL for LI. A listed country also returns the territories GeoNames files under it (GB also returns IM, JE, and GG), each result naming its own country in countryCode. | |
| adminCode1 | No | First-level admin division (state, province, region) to search inside, by its GeoNames admin code: TX is Texas in US. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 1), or from adminCode1 on rows of geonames_search_places, geonames_get_hierarchy, and geonames_get_children. GeoNames codes are neither ISO 3166-2 nor postal admin codes: Bavaria is 02, not BY. Needs exactly one country in countries. 1 to 20 letters or digits, zero padding kept (02, not 2). Case-insensitive. | |
| adminCode2 | No | Second-level admin division (a US county, a French département) to search inside, by its GeoNames admin code: 033 is King County in WA. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 2). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept (033, not 33). Case-insensitive. | |
| adminCode3 | No | Third-level admin division to search inside, by its GeoNames admin code: 09162 is Munich in DE. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 3). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept. Case-insensitive. | |
| adminCode4 | No | Fourth-level admin division to search inside, by its GeoNames admin code: 92012 is Boulogne-Billancourt in FR. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 4). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept. Case-insensitive. | |
| boundingBox | No | Keep only places inside this box. The box cannot cross the 180° meridian: split such an area into two searches. | |
| featureCodes | No | GeoNames feature codes (PPLC capital, ADM1 state, MT mountain, AIRP airport), up to 20, as a list. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code. | |
| featureClasses | No | GeoNames feature classes: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone. | |
| geonamesUsername | No | Your own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit applied: limit as given, or 100 when it asked for more. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Places returned on this page. | |
| notice | No | Guidance: why nothing matched, or how to reach the next page (naming a limit held to 100), and which places on the page lie in countries that countries does not list. | |
| places | No | Places on this page, in the requested order. | |
| truncated | No | True when more matching places remain past this page. | |
| nextOffset | No | Offset of the next page; absent on the last page and once offset is 5000. Capped at 5000, the last offset GeoNames' free service accepts, so that page can repeat rows of this one. | |
| totalCount | No | GeoNames' count of matching places, before paging. | |
| effectiveQuery | No | The match mode, query, and filters as the server sent them to GeoNames. |