Find GeoNames postal codes
geonames_find_postal_codesLook 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"mode": "<mode>"
},
"name": "geonames_find_postal_codes"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude in decimal degrees, -90 to 90. Required in mode nearby. | |
| lng | No | Longitude in decimal degrees, -180 to 180. Required in mode nearby. | |
| mode | Yes | 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 | 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. | |
| offset | No | 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 | No | Search radius in kilometres for mode nearby, above 0 and at most 30 (GeoNames' free-tier limit). Default 10. | |
| countries | No | 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 | No | 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 | No | 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 | 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. | |
| mode | No | The lookup mode that ran. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Postal codes returned on this page. | |
| notice | No | Guidance: why nothing matched or nothing lies at offset, or how to reach the postal codes past this page (naming a limit held to 100), and which postal codes on the page lie in countries that countries does not list. | |
| truncated | No | True when more postal codes remain past this page; in mode nearby, more lie within radiusKm. | |
| nextOffset | No | Offset of the next page in modes code and place_name; absent on the last page, in mode nearby, and once offset is 5000. Capped at 5000, the last offset GeoNames' free service accepts, so that page can repeat rows of this one. | |
| postalCodes | No | Matching postal codes on this page; nearest first in mode nearby. |