Skip to main content
Glama

Search GeoNames places

geonames_search_places
Read-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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
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.
matchNoHow 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.
queryNoPlace 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).
citiesNoKeep 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.
offsetNoEntries to skip before the first one returned, for paging, 0 to 5000. Default 0.
orderByNoResult order: relevance or population, largest first. Omit it for GeoNames' own order, which matches relevance except with match name_prefix.
countriesNoISO 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.
adminCode1NoFirst-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.
adminCode2NoSecond-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.
adminCode3NoThird-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.
adminCode4NoFourth-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.
boundingBoxNoKeep only places inside this box. The box cannot cross the 180° meridian: split such an area into two searches.
featureCodesNoGeoNames 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.
featureClassesNoGeoNames 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.
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.
errorNoPresent when the call failed. Absent on success.
shownNoPlaces returned on this page.
noticeNoGuidance: 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.
placesNoPlaces on this page, in the requested order.
truncatedNoTrue when more matching places remain past this page.
nextOffsetNoOffset 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.
totalCountNoGeoNames' count of matching places, before paging.
effectiveQueryNoThe match mode, query, and filters as the server sent them to GeoNames.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed16 schema fields changed
    • addedInput schema / properties / adminCode1
      Added value: +{
      +  "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.",
      +  "pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
      +  "type": "string"
      +}
    • addedInput schema / properties / adminCode2
      Added value: +{
      +  "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.",
      +  "pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
      +  "type": "string"
      +}
    • addedInput schema / properties / adminCode3
      Added value: +{
      +  "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.",
      +  "pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
      +  "type": "string"
      +}
    • addedInput schema / properties / adminCode4
      Added value: +{
      +  "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.",
      +  "pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
      +  "type": "string"
      +}
    • changedInput schema / properties / cities / description
      Previous value: -"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. Case-insensitive."New value: +"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."
    • changedInput schema / properties / countries / description
      Previous value: -"ISO 3166-1 country 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."New value: +"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."
    • changedInput schema / properties / featureClasses / description
      Previous value: -"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. A list or a comma-separated string; case-insensitive. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone."New value: +"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."
    • changedInput schema / properties / featureCodes / description
      Previous value: -"GeoNames feature codes (PPLC capital, ADM1 state, MT mountain, AIRP airport), up to 20, as a list or a comma-separated string. Case-insensitive; a class prefix (P.PPLC) is dropped. 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."New value: +"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."
    • 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 / match / description
      Previous value: -"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. Case-insensitive."New value: +"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."
    • changedInput schema / properties / orderBy / description
      Previous value: -"Result order: relevance (GeoNames' default) or population, largest first. Case-insensitive."New value: +"Result order: relevance or population, largest first. Omit it for GeoNames' own order, which matches relevance except with match name_prefix."
    • 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: `query_or_filter_required`: Neither query nor a narrowing filter (countries, featureClasses, featureCodes, boundingBox) was given. `query_required`: match was set without query. `unknown_country_code`: A countries entry is a well-formed alpha-3 or three-digit numeric code that no country has. `unknown_feature_code`: A featureCodes entry is not a GeoNames feature code. `feature_filter_mismatch`: featureClasses and featureCodes are both set and a code's class is not listed or a listed class has no listed code, or cities (class P only) is set beside another class or a code outside class P. GeoNames intersects the filters, so those entries match nothing. `invalid_bounding_box`: boundingBox has south greater than or equal to north, or west greater than or equal to east. `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: `query_or_filter_required`: Neither query nor a narrowing filter (countries, featureClasses, featureCodes, boundingBox) was given. `query_required`: match was set without query. `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. `unknown_feature_code`: A featureCodes entry is not a GeoNames feature code. `admin_code_unscoped`: An admin code is set without exactly one country in countries, or adminCode2 to adminCode4 without adminCode1: codes repeat across countries, and lower-level codes across first-level divisions. `feature_filter_mismatch`: featureClasses and featureCodes are both set and a code's class is not listed or a listed class has no listed code, or cities (class P only) is set beside another class or a code outside class P. GeoNames intersects the filters, so those entries match nothing. `invalid_bounding_box`: boundingBox has south greater than or equal to north, or west greater than or equal to east. `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."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "query_or_filter_required",
      -  "query_required",
      -  "unknown_country_code",
      -  "unknown_feature_code",
      -  "feature_filter_mismatch",
      -  "invalid_bounding_box",
      -  "username_required",
      -  "caller_account_rejected",
      -  "server_account_rejected",
      -  "quota_exhausted",
      -  "upstream_rejected_parameter"
      -]New value: +[
      +  "query_or_filter_required",
      +  "query_required",
      +  "unknown_country_code",
      +  "unknown_feature_code",
      +  "admin_code_unscoped",
      +  "feature_filter_mismatch",
      +  "invalid_bounding_box",
      +  "username_required",
      +  "caller_account_rejected",
      +  "server_account_rejected",
      +  "quota_exhausted",
      +  "upstream_rejected_parameter"
      +]
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when nothing matched or more pages remain."New value: +"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."
  2. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context on top: the cost model (1 GeoNames credit per call) and the precise default matching semantics, which is not something the annotations convey.

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?

One long but well front-loaded passage: the search capability and filter vocabulary come first, then the match semantics and cost. The parenthetical code examples are somewhat redundant with the schema and inflate the sentence, but nearly every clause earns its place for an agent scanning the filter space.

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

Completeness4/5

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

For a 15-parameter, zero-required filter tool with a full output schema and exhaustive schema descriptions, the description covers purpose, filter vocabulary, default matching, cost, and downstream linkage. Pagination caps (100 per call) and the optional geonamesUsername auth path are left to the schema, which is acceptable given their depth there.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 15 parameters thoroughly. The description's filter cheat-sheets (P/PPLC/ADM1/MT/AIRP) and the adminCode1 TX + countries US example largely restate what the schema says, adding scanning convenience rather than new meaning; the baseline of 3 applies.

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?

States a specific verb and resource (search the GeoNames gazetteer of 13M+ places) plus the filter dimensions it accepts. It also differentiates itself from siblings by saying results carry the geonameId that geonames_get_place, geonames_get_hierarchy, and geonames_get_children consume, so the agent can place this tool in the workflow without opening another 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?

Gives clear operational context: filters can be combined, omitting query requires at least one of countries/featureClasses/featureCodes/boundingBox, and the default match requires a term in the place name ("Berlin, Germany"). It does not, however, state when to prefer a sibling such as geonames_reverse_geocode or geonames_find_postal_codes, so no explicit when-not guidance is present.

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.