Skip to main content
Glama

Find GeoNames postal codes

geonames_find_postal_codes
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
latNoLatitude in decimal degrees, -90 to 90. Required in mode nearby.
lngNoLongitude in decimal degrees, -180 to 180. Required in mode nearby.
modeYesWhat 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).
limitNoMaximum 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.
offsetNoPostal 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.
radiusKmNoSearch radius in kilometres for mode nearby, above 0 and at most 30 (GeoNames' free-tier limit). Default 10.
countriesNoCountries 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.
placeNameNoPlace 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.
postalCodeNoPostal 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.
geonamesUsernameNoYour 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

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit applied: limit as given, or 100 when it asked for more.
modeNoThe lookup mode that ran.
errorNoPresent when the call failed. Absent on success.
shownNoPostal codes returned on this page.
noticeNoGuidance: 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.
truncatedNoTrue when more postal codes remain past this page; in mode nearby, more lie within radiusKm.
nextOffsetNoOffset 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.
postalCodesNoMatching postal codes on this page; nearest first in mode nearby.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changed
    • changedInput schema / properties / countries / description
      Previous value: -"Keep only postal codes in these countries: ISO 3166-1 codes, up to 10, as a list or a comma-separated string: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. Case-insensitive; UK is accepted for GB. Modes code and place_name only."New value: +"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."
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum entries to return, 1 to 100. Default 10."New value: +"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."
    • changedInput schema / properties / limit / maximum
      Previous value: -100New value: +1000
    • changedInput schema / properties / mode / description
      Previous value: -"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). Case-insensitive."New value: +"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)."
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 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.",
      +  "maximum": 5000,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / postalCode / description
      Previous value: -"Postal code to resolve, such as 98101, SW1A 1AA, or K1A 0A1: letters, digits, spaces, and hyphens, up to 12 characters. Case and extra spaces are normalized. Required in mode code; in mode place_name it narrows the match; not used in mode nearby."New value: +"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."
    • changedOutput schema / properties / cap / description
      Previous value: -"The limit that was applied."New value: +"The limit applied: limit as given, or 100 when it asked for more."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `mode_fields_mismatch`: A field the mode requires is missing, or countries is given in mode nearby. The message names the field. `unknown_country_code`: A countries entry is a well-formed alpha-3 or three-digit numeric code that no country has. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `mode_fields_mismatch`: A field the mode requires is missing, or countries is given or offset above 0 in mode nearby. The message names the field. `unknown_country_code`: A countries entry, once mapped to alpha-2, is none of the 250 country codes or the retired AN, CS, and YU: an alpha-2 such as EL or EU, or an unassigned alpha-3 or numeric code. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."
    • addedOutput schema / properties / nextOffset
      Added value: +{
      +  "description": "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.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when nothing matched, or when a full page suggests more matches."New value: +"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."
    • changedOutput schema / properties / postalCodes / description
      Previous value: -"Matching postal codes; nearest first in mode nearby."New value: +"Matching postal codes on this page; nearest first in mode nearby."
    • changedOutput schema / properties / shown / description
      Previous value: -"Postal codes returned."New value: +"Postal codes returned on this page."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when a full page came back: GeoNames reports no total, so more may match."New value: +"True when more postal codes remain past this page; in mode nearby, more lie within radiusKm."
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent/openWorld annotations it discloses credit costs (1 credit, 2 for nearby, plus an extra credit when an empty code/place_name result at offset 0 reads the coverage list), caching of repeat lookups, the hard 100-per-call return cap despite limit allowing 1,000, and country-specific data quirks (Ireland, Malta, GB/CA/NL prefixes). This is exactly the operational context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single dense paragraph is front-loaded with purpose before mode and cost detail, and almost every clause carries information. It is long, however, and would scan faster with the three modes and the credit model broken into separate lines rather than one continuous block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need no explanation, and the description still covers all three modes, pagination limits, radius limits, credit accounting, caching, and the coverage-check sibling. An agent has everything needed for a 10-parameter tool with a required enum discriminator.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and each parameter already documents its mode-specific requirement. The description adds value on top by describing mode semantics as a whole (code/place_name page with offset up to 5000; nearby returns nearest-first) and tying credit cost to the selected mode.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Look up postal codes in the GeoNames postal database (122 countries)', then enumerates the three distinct lookup modes. An agent can distinguish this from siblings like search_places or reverse_geocode without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Mode selection is spelled out (resolve a code, find codes by place name, list codes near a coordinate), and it routes the agent to geonames_list_reference with topic postal_countries to check coverage. It stops short of explicit exclusions, e.g. it never says to prefer geonames_reverse_geocode over mode nearby when the goal is a place rather than postal codes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.