Search GeoNames places, walk admin hierarchies, reverse geocode, get postal codes and country info.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Look up postal codes in the GeoNames postal database (122 countries): mode code resolves a postal code to its place, admin names, and centroid; mode place_name finds postal codes for a place name; both page with offset, up to 5000; mode nearby lists postal codes within radiusKm (up to 30 km) of a coordinate, nearest first. Ireland returns only Eircode routing keys and Malta only the letter prefix; the United Kingdom (GB), Canada, and the Netherlands hold both full codes and their outward or district prefixes. Check coverage with geonames_list_reference topic postal_countries. Costs 1 GeoNames credit (2 for nearby); a code or place_name lookup with countries that returns nothing at offset 0 also reads the postal coverage list, 1 more credit unless that list is cached. Repeat lookups are cached.
What to look up. code: the place for postalCode (required). place_name: the postal codes of placeName (required). nearby: postal codes around lat and lng (both required; countries not accepted).
Latitude in decimal degrees, -90 to 90. Required in mode nearby.
Longitude in decimal degrees, -180 to 180. Required in mode nearby.
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.
Postal codes to skip before the first one returned, 0 to 5000. Default 0. Modes code and place_name only; pass the nextOffset of the previous page to read the next one.
Search radius in kilometres for mode nearby, above 0 and at most 30 (GeoNames' free-tier limit). Default 10.
Countries to look up postal codes in: ISO 3166-1 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 postal code's countryCode naming its own country. Modes code and place_name only.
Place name to find postal codes for, up to 100 characters. GeoNames matches it against place, admin, and country names. Required in mode place_name; in mode code it narrows the match; not used in mode nearby.
Postal code to resolve, such as 98101, SW1A 1AA, or K1A 0A1: capital letters, digits, spaces, and hyphens, up to 12 characters. Required in mode code; in mode place_name it narrows the match; not used in mode nearby.
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.
Look up postal codes in the GeoNames postal database (122 countries): mode code resolves a postal code to its place, admin names, and centroid; mode place_name finds postal codes for a place name; both page with offset, up to 5000; mode nearby lists postal codes within radiusKm (up to 30 km) of a coordinate, nearest first. Ireland returns only Eircode routing keys and Malta only the letter prefix; the United Kingdom (GB), Canada, and the Netherlands hold both full codes and their outward or district prefixes. Check coverage with geonames_list_reference topic postal_countries. Costs 1 GeoNames credit (2 for nearby); a code or place_name lookup with countries that returns nothing at offset 0 also reads the postal coverage list, 1 more credit unless that list is cached. Repeat lookups are cached.
| Argument | Type | Description |
|---|---|---|
| lat | number | Latitude in decimal degrees, -90 to 90. Required in mode nearby. |
| lng | number | Longitude in decimal degrees, -180 to 180. Required in mode nearby. |
| mode* | string | What to look up. code: the place for postalCode (required). place_name: the postal codes of placeName (required). nearby: postal codes around lat and lng (both required; countries not accepted). |
| limit | integer | 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. |
| offset | integer | Postal codes to skip before the first one returned, 0 to 5000. Default 0. Modes code and place_name only; pass the nextOffset of the previous page to read the next one. |
| radiusKm | number | Search radius in kilometres for mode nearby, above 0 and at most 30 (GeoNames' free-tier limit). Default 10. |
| countries | array | Countries to look up postal codes in: ISO 3166-1 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 postal code's countryCode naming its own country. Modes code and place_name only. |
| placeName | string | Place name to find postal codes for, up to 100 characters. GeoNames matches it against place, admin, and country names. Required in mode place_name; in mode code it narrows the match; not used in mode nearby. |
| postalCode | string | Postal code to resolve, such as 98101, SW1A 1AA, or K1A 0A1: capital letters, digits, spaces, and hyphens, up to 12 characters. Required in mode code; in mode place_name it narrows the match; not used in mode nearby. |
| geonamesUsername | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"mode"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude in decimal degrees, -90 to 90. Required in mode nearby."
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude in decimal degrees, -180 to 180. Required in mode nearby."
},
"mode": {
"enum": [
"code",
"place_name",
"nearby"
],
"type": "string",
"description": "What to look up. code: the place for postalCode (required). place_name: the postal codes of placeName (required). nearby: postal codes around lat and lng (both required; countries not accepted)."
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 1000,
"minimum": 1,
"description": "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."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 5000,
"minimum": 0,
"description": "Postal codes to skip before the first one returned, 0 to 5000. Default 0. Modes code and place_name only; pass the nextOffset of the previous page to read the next one."
},
"radiusKm": {
"type": "number",
"default": 10,
"maximum": 30,
"description": "Search radius in kilometres for mode nearby, above 0 and at most 30 (GeoNames' free-tier limit). Default 10.",
"exclusiveMinimum": 0
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^([A-Z]{2,3}|\\d{3})$",
"description": "ISO 3166-1 alpha-2, alpha-3, or three-digit numeric country code."
},
"maxItems": 10,
"description": "Countries to look up postal codes in: ISO 3166-1 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 postal code's countryCode naming its own country. Modes code and place_name only."
},
"placeName": {
"type": "string",
"maxLength": 100,
"description": "Place name to find postal codes for, up to 100 characters. GeoNames matches it against place, admin, and country names. Required in mode place_name; in mode code it narrows the match; not used in mode nearby."
},
"postalCode": {
"type": "string",
"pattern": "^[A-Z0-9][A-Z0-9 -]{0,11}$",
"description": "Postal code to resolve, such as 98101, SW1A 1AA, or K1A 0A1: capital letters, digits, spaces, and hyphens, up to 12 characters. Required in mode code; in mode place_name it narrows the match; not used in mode nearby."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "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."
}
},
"additionalProperties": false
}List the direct children of a GeoNames feature — Earth's continents, a continent's countries, a country's first-level divisions, a state's counties, a city's sections — in the administrative tree, or in the tourism tree (islands, coasts, and their municipalities; almost all in Spain) or the dependency tree (a country's dependent territories). Start from a country's geonameId (geonames_get_countries) or any admin division's. Children are mostly admin divisions (class A) and populated places (class P); continents and coasts are class L and islands class T. For other feature types inside a place, use geonames_search_places with a boundingBox. GeoNames answers a tourism or dependency request with the administrative children when the feature has no such tree, so the tool compares the two lists and sets sameAsAdministrative when they match, keeping the rows (a real tree can match too). The full child list is fetched once (1 GeoNames credit) and cached, so paging and nameContains filtering are free; a tourism or dependency call also reads the administrative list for the comparison, 1 more credit unless it is cached.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum entries to return, 1 to 1,000. This tool returns at most 500 per call: a larger limit is held to 500, and the notice says so when more entries remain. Default 100. |
| offset | integer | Entries to skip before the first one returned, for paging. Default 0. |
| geonameId* | string | GeoNames id of the parent feature as a digit string up to 2147483647, such as "6252001" (United States): the geonameId the other geonames tools return, sent as a string. |
| hierarchy |
Get GeoNames country facts — ISO alpha-2, alpha-3, and numeric codes, FIPS code, geonameId, capital, population, area in km², continent, languages, currency, postal-code format, and mainland bounding box — for the countries named, a continent, or all 250. The geonameId anchors geonames_get_children (a country's first-level divisions) and geonames_get_hierarchy. The full table is fetched once a day (1 GeoNames credit) and cached.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum entries to return, 1 to 1,000. This tool returns at most 250 per call: a larger limit is held to 250, and the notice says so when more entries remain. Default 50. |
| offset | integer | Entries to skip before the first one returned, for paging. Default 0. |
| continent | string | Keep only countries on this continent: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America. |
| countries | array | Countries to return by ISO 3166-1 code: alpha-2 (US), alpha-3 (USA), or three-digit numeric (840), up to 250, as a list. UK is accepted for GB and FL for LI. Match country names with nameContains instead. |
| nameContains | string | Keep only countries whose English name contains every word of this text as a substring (niger also matches Nigeria), ignoring case, accents, and punctuation. |
| geonamesUsername |
Return the parent chain of a GeoNames feature, ordered from Earth and its continent through the country and admin divisions down to the feature itself, each with its geonameId, feature code, and coordinates. Use it to find which country, state, and county contain a place, or to fill an admin path for a geonameId. An unknown id returns found: false. Costs 1 GeoNames credit; cached.
| Argument | Type | Description |
|---|---|---|
| geonameId* | string | GeoNames feature id as a digit string up to 2147483647, such as "5809844" (Seattle): the geonameId the other geonames tools return, sent as a string. |
| geonamesUsername | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geonameId"
],
"properties": {
"geonameId": {
"type": "string",
"pattern": "^[1-9]\\d*$",
"description": "GeoNames feature id as a digit string up to 2147483647, such as \"5809844\" (Seattle): the geonameId the other geonames tools return, sent as a string."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "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."
}
},
"additionalProperties": false
}Fetch the full GeoNames record for one geonameId: coordinates, feature type, the admin chain with each level's code, name, and geonameId, timezone, bounding box, recorded and DEM elevation, population, Wikipedia URL, names in other languages, postal codes, and external identifiers (IATA, ICAO, UN/LOCODE, Wikidata). Take the geonameId from geonames_search_places, geonames_reverse_geocode, geonames_get_children, or geonames_get_countries. An unknown id returns found: false. Costs 1 GeoNames credit; repeat lookups are cached.
| Argument | Type | Description |
|---|---|---|
| geonameId* | string | GeoNames feature id as a digit string up to 2147483647, such as "5809844" (Seattle): the geonameId the other geonames tools return, sent as a string. |
| nameLanguages | array | Keep only alternate names in these languages, up to 20, as a list. A tag also matches its regional forms: zh keeps names GeoNames tags zh, zh-CN, or zh-TW. Omit to return every alternate name, including those under GeoNames pseudo-language tags (abbr, phon, piny, fr_1793), which this filter cannot select. Postal codes, links, and identifiers are unaffected. |
| geonamesUsername | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geonameId"
],
"properties": {
"geonameId": {
"type": "string",
"pattern": "^[1-9]\\d*$",
"description": "GeoNames feature id as a digit string up to 2147483647, such as \"5809844\" (Seattle): the geonameId the other geonames tools return, sent as a string."
},
"nameLanguages": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z]{2,3}(-[a-z0-9]{2,8})*$",
"description": "Language tag or prefix, such as en, de, or zh-tw."
},
"maxItems": 20,
"description": "Keep only alternate names in these languages, up to 20, as a list. A tag also matches its regional forms: zh keeps names GeoNames tags zh, zh-CN, or zh-TW. Omit to return every alternate name, including those under GeoNames pseudo-language tags (abbr, phon, piny, fr_1793), which this filter cannot select. Postal codes, links, and identifiers are unaffected."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "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."
}
},
"additionalProperties": false
}Decode GeoNames vocabulary used by the other tools: topic feature_classes lists the 9 one-letter classes; topic feature_codes lists the 684 feature codes with names and definitions, filterable by class and text; topic postal_countries lists the 122 countries with postal-code data and each one's code range and count. feature_classes and feature_codes are bundled and spend no credits; postal_countries costs 1 GeoNames credit a day (cached).
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum entries to return, 1 to 1,000. This tool returns at most 700 per call: a larger limit is held to 700, and the notice says so when more entries remain. Default 100. |
| topic* | string | Vocabulary to list: feature_classes (the 9 one-letter classes), feature_codes (the 684 codes), or postal_countries (countries with postal-code data). |
| offset | integer | Entries to skip before the first one returned, for paging. Default 0. |
| featureClass | string | Topic feature_codes only: keep the codes of this one-letter class (A, H, L, P, R, S, T, U, V). |
| nameContains | string | Keep only entries whose code, name, or description contains every word of this text as a substring (port also matches airport), ignoring case, accents, and punctuation. |
| geonamesUsername | string |
Resolve a latitude/longitude to the country and admin subdivisions that contain it (down to ADM5, each with its geonameId and ISO 3166-2 code where one exists), or the ocean or sea when the point is offshore, plus the nearest populated places with distances; these include neighborhood sections (PPLX) and historical places (PPLH), marked by featureCode. Set featureClasses or featureCodes to list the nearest features of that type instead (peaks, lakes, airports), cities to keep only places above a population tier, and includeTimezone for the IANA timezone with local time, sunrise, and sunset (offshore points get only GeoNames' UTC-offset estimate). A harbor, pier, or shoreline point can fall just outside every country outline and resolve to the sea; coastalBufferKm (up to 50) matches the nearest country within that distance instead. Costs 1 GeoNames credit for containment, with or without the buffer, plus 3 for nearest populated places or 4 for nearest features (nearbyLimit 0 skips them), 1 for the ocean when no country contains the point or lies within the buffer, and 1 for the timezone.
| Argument | Type | Description |
|---|---|---|
| lat* | number | Latitude in decimal degrees, -90 to 90. |
| lng* | number | Longitude in decimal degrees, -180 to 180. |
| cities | string | Keep only nearby populated places with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. Not combinable with featureClasses or featureCodes. |
| radiusKm | number |
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.
| Argument | Type | Description |
|---|---|---|
| limit | integer | 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 | string | 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 | string | 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 | string | 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. Beside featureClasses or featureCodes, list only class P or class-P codes such as PPLC. |
| string |
| Which tree to descend: administrative (the default: continents (class L), countries, admin divisions, populated places), tourism (islands (class T), coasts (class L), and their municipalities; almost all in Spain), or dependency (a country's dependent territories). For a feature with no tourism or dependency tree, GeoNames answers with its administrative children, which sameAsAdministrative flags; the comparison reads the administrative list, 1 more credit unless it is cached. |
| nameContains | string | Keep only children whose name or toponym name contains every word of this text as a substring (kansas also matches Arkansas), ignoring case, accents, and punctuation. |
| geonamesUsername | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geonameId"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 1000,
"minimum": 1,
"description": "Maximum entries to return, 1 to 1,000. This tool returns at most 500 per call: a larger limit is held to 500, and the notice says so when more entries remain. Default 100."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries to skip before the first one returned, for paging. Default 0."
},
"geonameId": {
"type": "string",
"pattern": "^[1-9]\\d*$",
"description": "GeoNames id of the parent feature as a digit string up to 2147483647, such as \"6252001\" (United States): the geonameId the other geonames tools return, sent as a string."
},
"hierarchy": {
"enum": [
"administrative",
"tourism",
"dependency"
],
"type": "string",
"default": "administrative",
"description": "Which tree to descend: administrative (the default: continents (class L), countries, admin divisions, populated places), tourism (islands (class T), coasts (class L), and their municipalities; almost all in Spain), or dependency (a country's dependent territories). For a feature with no tourism or dependency tree, GeoNames answers with its administrative children, which sameAsAdministrative flags; the comparison reads the administrative list, 1 more credit unless it is cached."
},
"nameContains": {
"type": "string",
"maxLength": 100,
"description": "Keep only children whose name or toponym name contains every word of this text as a substring (kansas also matches Arkansas), ignoring case, accents, and punctuation."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "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."
}
},
"additionalProperties": false
}| string |
| Your own GeoNames username, spent only when the country table is not already cached, so the call uses that account's credit instead of the server's. The account needs free web services enabled on its geonames.org account page. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"maximum": 1000,
"minimum": 1,
"description": "Maximum entries to return, 1 to 1,000. This tool returns at most 250 per call: a larger limit is held to 250, and the notice says so when more entries remain. Default 50."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries to skip before the first one returned, for paging. Default 0."
},
"continent": {
"enum": [
"AF",
"AN",
"AS",
"EU",
"NA",
"OC",
"SA"
],
"type": "string",
"description": "Keep only countries on this continent: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^([A-Z]{2,3}|\\d{3})$",
"description": "ISO 3166-1 alpha-2, alpha-3, or three-digit numeric country code."
},
"maxItems": 250,
"description": "Countries to return by ISO 3166-1 code: alpha-2 (US), alpha-3 (USA), or three-digit numeric (840), up to 250, as a list. UK is accepted for GB and FL for LI. Match country names with nameContains instead."
},
"nameContains": {
"type": "string",
"maxLength": 100,
"description": "Keep only countries whose English name contains every word of this text as a substring (niger also matches Nigeria), ignoring case, accents, and punctuation."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Your own GeoNames username, spent only when the country table is not already cached, so the call uses that account's credit instead of the server's. The account needs free web services enabled on its geonames.org account page."
}
},
"additionalProperties": false
}| Topic postal_countries only, and only when the list is not already cached: your own GeoNames username, so the call spends that account's credit instead of the server's. The account needs free web services enabled on its geonames.org account page. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"topic"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 1000,
"minimum": 1,
"description": "Maximum entries to return, 1 to 1,000. This tool returns at most 700 per call: a larger limit is held to 700, and the notice says so when more entries remain. Default 100."
},
"topic": {
"enum": [
"feature_classes",
"feature_codes",
"postal_countries"
],
"type": "string",
"description": "Vocabulary to list: feature_classes (the 9 one-letter classes), feature_codes (the 684 codes), or postal_countries (countries with postal-code data)."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries to skip before the first one returned, for paging. Default 0."
},
"featureClass": {
"enum": [
"A",
"H",
"L",
"P",
"R",
"S",
"T",
"U",
"V"
],
"type": "string",
"description": "Topic feature_codes only: keep the codes of this one-letter class (A, H, L, P, R, S, T, U, V)."
},
"nameContains": {
"type": "string",
"maxLength": 100,
"description": "Keep only entries whose code, name, or description contains every word of this text as a substring (port also matches airport), ignoring case, accents, and punctuation."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Topic postal_countries only, and only when the list is not already cached: your own GeoNames username, so the call spends that account's credit instead of the server's. The account needs free web services enabled on its geonames.org account page."
}
},
"additionalProperties": false
}| Radius in kilometres for the nearby lookup, above 0 and at most 300 (GeoNames' free-tier limit). Default 20. |
| nearbyLimit | integer | How many nearest places or features to list, 0 to 1,000. This tool returns at most 50 per call: a larger nearbyLimit is held to 50, and the notice says so when more lie within the radius. Default 5. 0 skips the nearby lookup and its 3 or 4 credits. |
| featureCodes | array | List the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, 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. Not combinable with cities. |
| featureClasses | array | List the nearest features of these GeoNames classes instead of populated places: 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. Not combinable with cities. |
| coastalBufferKm | number | When no country contains the point, match the nearest country within this many kilometres, 0 to 50. Default 0: exact containment only. Set it for a harbor, pier, or shoreline point, which can fall just outside a country's outline as GeoNames maps it and otherwise resolves to the sea; a match carries country.distanceInKm. The nearby and timezone lookups keep the exact point. No extra credit. |
| includeTimezone | boolean | Also return the timezone: IANA id, UTC offsets, local time, sunrise, and sunset (1 more credit). Default false. |
| geonamesUsername | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude in decimal degrees, -90 to 90."
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude in decimal degrees, -180 to 180."
},
"cities": {
"enum": [
"cities1000",
"cities5000",
"cities15000"
],
"type": "string",
"description": "Keep only nearby populated places with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. Not combinable with featureClasses or featureCodes."
},
"radiusKm": {
"type": "number",
"default": 20,
"maximum": 300,
"description": "Radius in kilometres for the nearby lookup, above 0 and at most 300 (GeoNames' free-tier limit). Default 20.",
"exclusiveMinimum": 0
},
"nearbyLimit": {
"type": "integer",
"default": 5,
"maximum": 1000,
"minimum": 0,
"description": "How many nearest places or features to list, 0 to 1,000. This tool returns at most 50 per call: a larger nearbyLimit is held to 50, and the notice says so when more lie within the radius. Default 5. 0 skips the nearby lookup and its 3 or 4 credits."
},
"featureCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z0-9]{2,5}$",
"description": "GeoNames feature code without its class prefix."
},
"maxItems": 20,
"description": "List the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, 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. Not combinable with cities."
},
"featureClasses": {
"type": "array",
"items": {
"enum": [
"A",
"H",
"L",
"P",
"R",
"S",
"T",
"U",
"V"
],
"type": "string",
"description": "One-letter GeoNames feature class."
},
"maxItems": 9,
"description": "List the nearest features of these GeoNames classes instead of populated places: 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. Not combinable with cities."
},
"coastalBufferKm": {
"type": "number",
"default": 0,
"maximum": 50,
"minimum": 0,
"description": "When no country contains the point, match the nearest country within this many kilometres, 0 to 50. Default 0: exact containment only. Set it for a harbor, pier, or shoreline point, which can fall just outside a country's outline as GeoNames maps it and otherwise resolves to the sea; a match carries country.distanceInKm. The nearby and timezone lookups keep the exact point. No extra credit."
},
"includeTimezone": {
"type": "boolean",
"default": false,
"description": "Also return the timezone: IANA id, UTC offsets, local time, sunrise, and sunset (1 more credit). Default false."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "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."
}
},
"additionalProperties": false
}| offset | integer | Entries to skip before the first one returned, for paging, 0 to 5000. Default 0. |
| orderBy | string | Result order: relevance or population, largest first. Omit it for GeoNames' own order, which matches relevance except with match name_prefix. |
| countries | array | 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 | string | 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 | string | 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 | string | 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 | string | 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 | object | Keep only places inside this box. The box cannot cross the 180° meridian: split such an area into two searches. |
| featureCodes | array | 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 | array | 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 | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"limit": {
"type": "integer",
"default": 10,
"maximum": 1000,
"minimum": 1,
"description": "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": {
"enum": [
"name_required",
"any_field",
"exact_name",
"name_prefix"
],
"type": "string",
"description": "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": {
"type": "string",
"maxLength": 200,
"description": "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": {
"enum": [
"cities1000",
"cities5000",
"cities15000"
],
"type": "string",
"description": "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. Beside featureClasses or featureCodes, list only class P or class-P codes such as PPLC."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 5000,
"minimum": 0,
"description": "Entries to skip before the first one returned, for paging, 0 to 5000. Default 0."
},
"orderBy": {
"enum": [
"relevance",
"population"
],
"type": "string",
"description": "Result order: relevance or population, largest first. Omit it for GeoNames' own order, which matches relevance except with match name_prefix."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^([A-Z]{2,3}|\\d{3})$",
"description": "ISO 3166-1 alpha-2, alpha-3, or three-digit numeric country code."
},
"maxItems": 10,
"description": "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": {
"type": "string",
"pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
"description": "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": {
"type": "string",
"pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
"description": "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": {
"type": "string",
"pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
"description": "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": {
"type": "string",
"pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
"description": "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": {
"type": "object",
"required": [
"north",
"south",
"east",
"west"
],
"properties": {
"east": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Eastern longitude bound, decimal degrees, -180 to 180."
},
"west": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Western longitude bound, decimal degrees, -180 to 180; below east."
},
"north": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Northern latitude bound, decimal degrees, -90 to 90."
},
"south": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Southern latitude bound, decimal degrees, -90 to 90; below north."
}
},
"description": "Keep only places inside this box. The box cannot cross the 180° meridian: split such an area into two searches.",
"additionalProperties": false
},
"featureCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z0-9]{2,5}$",
"description": "GeoNames feature code without its class prefix."
},
"maxItems": 20,
"description": "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": {
"type": "array",
"items": {
"enum": [
"A",
"H",
"L",
"P",
"R",
"S",
"T",
"U",
"V"
],
"type": "string",
"description": "One-letter GeoNames feature class."
},
"maxItems": 9,
"description": "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": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "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."
}
},
"additionalProperties": false
}