geonames-mcp-server

{'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). Case-insensitive.'}, 'limit': {'type': 'integer', 'default': 10, 'maximum': 100, 'minimum': 1, 'description': 'Maximum entries to return, 1 to 100. Default 10.'}, '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': '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.'}, '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: 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.'}, '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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['mode', 'postalCodes', 'truncated', 'shown', 'cap']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied.'}, 'mode': {'enum': ['code', 'place_name', 'nearby'], 'type': 'string', 'description': 'The lookup mode that ran.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['mode_fields_mismatch', 'unknown_country_code', 'username_required', 'caller_account_rejected', 'server_account_rejected', 'quota_exhausted', 'upstream_rejected_parameter'], 'description': "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."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Postal codes returned.'}, 'notice': {'type': 'string', 'description': 'Guidance when nothing matched, or when a full page suggests more matches.'}, 'truncated': {'type': 'boolean', 'description': 'True when a full page came back: GeoNames reports no total, so more may match.'}, 'postalCodes': {'type': 'array', 'items': {'type': 'object', 'required': ['postalCode', 'placeName', 'countryCode'], 'properties': {'lat': {'type': 'number', 'description': "Latitude of the postal code's centroid in decimal degrees. In mode nearby, the first US row is the query point itself (GeoNames resolves it from ZIP-code areas). Absent when GeoNames sent none."}, 'lng': {'type': 'number', 'description': "Longitude of the postal code's centroid in decimal degrees; same caveat as lat. Absent when GeoNames sent none."}, 'iso3166_2': {'type': 'string', 'description': 'ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO. Not sent in mode nearby.'}, 'placeName': {'type': 'string', 'description': 'Place the postal code serves.'}, 'adminCode1': {'type': 'string', 'description': 'First-order admin division code (state, province).'}, 'adminCode2': {'type': 'string', 'description': 'Second-order admin division code (county, district).'}, 'adminCode3': {'type': 'string', 'description': 'Third-order admin division code.'}, 'adminName1': {'type': 'string', 'description': 'First-order admin division name.'}, 'adminName2': {'type': 'string', 'description': 'Second-order admin division name.'}, 'adminName3': {'type': 'string', 'description': 'Third-order admin division name.'}, 'postalCode': {'type': 'string', 'description': 'The postal code, as GeoNames stores it.'}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 country code.'}, 'distanceInKm': {'type': 'number', 'description': 'Distance from the query point in kilometres. Mode nearby only; absent when GeoNames sent none.'}}, 'description': 'One postal code.', 'additionalProperties': False}, 'description': 'Matching postal codes; nearest first in mode nearby.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['geonameId'], 'properties': {'limit': {'type': 'integer', 'default': 100, 'maximum': 500, 'minimum': 1, 'description': 'Maximum entries to return, 1 to 500. 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, a positive integer up to 2147483647 such as 6252001 (United States), as returned in geonameId by the other geonames tools. A geonames.org/<id> URL is reduced to its id.'}, '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. Case-insensitive."}, '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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['found', 'parentGeonameId', 'hierarchy', 'children', 'totalCount', 'truncated', 'shown', 'cap']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['username_required', 'caller_account_rejected', 'server_account_rejected', 'quota_exhausted', 'upstream_rejected_parameter'], 'description': "Machine-readable failure mode. Declared by this tool: `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."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'found': {'type': 'boolean', 'description': 'False when GeoNames has no feature with this geonameId.'}, 'shown': {'type': 'number', 'description': 'Children returned on this page.'}, 'notice': {'type': 'string', 'description': 'Guidance when a tourism or dependency answer is the administrative children, there are no children, nothing matched, the offset is past the end, more pages remain, or GeoNames holds more children than it returns.'}, 'children': {'type': 'array', 'items': {'type': 'object', 'required': ['geonameId', 'name', 'toponymName'], 'properties': {'lat': {'type': 'number', 'description': 'Latitude in decimal degrees. Absent when GeoNames sent none.'}, 'lng': {'type': 'number', 'description': 'Longitude in decimal degrees. Absent when GeoNames sent none.'}, 'name': {'type': 'string', 'description': 'Name of the child, as GeoNames displays it.'}, 'geonameId': {'type': 'number', 'description': 'GeoNames feature id of the child: pass it to geonames_get_children again to descend further, or to geonames_get_place.'}, 'iso3166_2': {'type': 'string', 'description': 'ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO.'}, 'adminCode1': {'type': 'string', 'description': 'Code of the first-order admin division containing it.'}, 'adminName1': {'type': 'string', 'description': 'Name of the first-order admin division containing it.'}, 'population': {'type': 'number', 'description': 'Population. Absent when GeoNames records none.'}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 code of the containing country.'}, 'featureCode': {'type': 'string', 'description': 'Feature code, such as ADM1 (first-order division) or PPLX (section).'}, 'featureName': {'type': 'string', 'description': "GeoNames' name for the feature code."}, 'toponymName': {'type': 'string', 'description': "GeoNames' main name for the feature, often the local-language form."}, 'featureClass': {'type': 'string', 'description': 'One-letter feature class (A admin division, P populated place, â\x80¦).'}}, 'description': 'One child feature.', 'additionalProperties': False}, 'description': "Children on this page, in GeoNames' order; empty when found is false or the feature has none."}, 'guidance': {'type': 'string', 'description': 'What to do next; present only when found is false.'}, 'hierarchy': {'enum': ['administrative', 'tourism', 'dependency'], 'type': 'string', 'description': 'The tree that was descended.'}, 'truncated': {'type': 'boolean', 'description': 'True when more children remain past this page.'}, 'nextOffset': {'type': 'number', 'description': 'Offset of the next page; absent on the last page.'}, 'totalCount': {'type': 'number', 'description': 'Children matching nameContains, before paging.'}, 'parentGeonameId': {'type': 'number', 'description': 'The geonameId whose children were requested.'}, 'sameAsAdministrative': {'type': 'boolean', 'description': 'Tourism and dependency trees only, when the feature has children there: true when they are exactly its administrative children (same geonameIds and total). GeoNames answers with the administrative children when a feature has no such tree, so true most likely means it has none; a real tree can also match.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'limit': {'type': 'integer', 'default': 50, 'maximum': 250, 'minimum': 1, 'description': 'Maximum entries to return, 1 to 250. 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. Case-insensitive.'}, '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': 50, 'description': 'Countries to return by ISO 3166-1 code: alpha-2 (US), alpha-3 (USA), or three-digit numeric (840), up to 50, as a list or a comma-separated string. Case-insensitive; UK is accepted for GB. 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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['countries', 'notFound', 'totalCount', 'truncated', 'shown', 'cap']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['username_required', 'caller_account_rejected', 'server_account_rejected', 'quota_exhausted', 'upstream_rejected_parameter'], 'description': "Machine-readable failure mode. Declared by this tool: `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."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Countries returned on this page.'}, 'notice': {'type': 'string', 'description': 'Guidance when nothing matched, the offset is past the end, or more pages remain.'}, 'notFound': {'type': 'array', 'items': {'type': 'string', 'description': 'A requested code.'}, 'description': 'Requested codes that match no GeoNames country; empty when every code matched.'}, 'countries': {'type': 'array', 'items': {'type': 'object', 'required': ['countryCode', 'isoAlpha3', 'countryName', 'geonameId', 'continentCode', 'continentName', 'languages', 'boundingBox'], 'properties': {'capital': {'type': 'string', 'description': 'Capital city name. Absent where GeoNames gives none.'}, 'fipsCode': {'type': 'string', 'description': 'FIPS 10-4 country code. Absent where GeoNames gives none.'}, 'geonameId': {'type': 'number', 'description': "The country's GeoNames feature id: pass it to geonames_get_children for its first-level divisions, or to geonames_get_place."}, 'isoAlpha3': {'type': 'string', 'description': 'ISO 3166-1 alpha-3 code.'}, 'languages': {'type': 'array', 'items': {'type': 'string', 'description': 'A language tag such as en-US or haw.'}, 'description': 'Languages spoken, most used first, as GeoNames lists them.'}, 'areaInSqKm': {'type': 'number', 'description': 'Area in square kilometres. Absent where GeoNames gives none.'}, 'isoNumeric': {'type': 'string', 'description': 'ISO 3166-1 numeric code. Absent where ISO assigns none (Kosovo) or GeoNames gives none.'}, 'population': {'type': 'number', 'description': 'Population as GeoNames records it. Absent where GeoNames gives none.'}, 'boundingBox': {'type': 'object', 'required': ['north', 'south', 'east', 'west'], 'properties': {'east': {'type': 'number', 'description': 'Eastern longitude bound, decimal degrees.'}, 'west': {'type': 'number', 'description': 'Western longitude bound, decimal degrees.'}, 'north': {'type': 'number', 'description': 'Northern latitude bound, decimal degrees.'}, 'south': {'type': 'number', 'description': 'Southern latitude bound, decimal degrees.'}}, 'description': "Bounding box of the country's mainland.", 'additionalProperties': False}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 code.'}, 'countryName': {'type': 'string', 'description': "GeoNames' English country name."}, 'currencyCode': {'type': 'string', 'description': 'ISO 4217 currency code. Absent where GeoNames gives none.'}, 'continentCode': {'type': 'string', 'description': 'Continent code: AF, AN, AS, EU, NA, OC, or SA.'}, 'continentName': {'type': 'string', 'description': 'Continent name.'}, 'postalCodeFormat': {'type': 'string', 'description': 'Postal-code pattern (# a digit, @ a letter). Absent for countries without postal codes.'}}, 'description': 'One country.', 'additionalProperties': False}, 'description': 'Countries on this page, in GeoNames order (by alpha-2 code).'}, 'truncated': {'type': 'boolean', 'description': 'True when more countries remain past this page.'}, 'nextOffset': {'type': 'number', 'description': 'Offset of the next page; absent on the last page.'}, 'totalCount': {'type': 'number', 'description': 'Countries matching the filters, before paging.'}}, 'additionalProperties': False}

{'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, a positive integer up to 2147483647 such as 5809844 (Seattle), as returned in geonameId by the other geonames tools. A geonames.org/<id> URL is reduced to its id.'}, '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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['found', 'geonameId', 'chain']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'chain': {'type': 'array', 'items': {'type': 'object', 'required': ['geonameId', 'name', 'toponymName'], 'properties': {'lat': {'type': 'number', 'description': 'Latitude in decimal degrees. Absent when GeoNames sent none.'}, 'lng': {'type': 'number', 'description': 'Longitude in decimal degrees. Absent when GeoNames sent none.'}, 'name': {'type': 'string', 'description': 'Name of this level, as GeoNames displays it.'}, 'geonameId': {'type': 'number', 'description': 'GeoNames feature id of this level.'}, 'iso3166_2': {'type': 'string', 'description': 'ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO.'}, 'adminCode1': {'type': 'string', 'description': 'First-order admin division code. Absent above that level.'}, 'population': {'type': 'number', 'description': 'Population. Absent when GeoNames records none.'}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 country code. Absent on Earth and continent rows.'}, 'featureCode': {'type': 'string', 'description': 'Feature code: AREA (Earth), CONT, PCLI (country), ADM1â\x80\x93ADM5, PPL, â\x80¦'}, 'featureName': {'type': 'string', 'description': "GeoNames' name for the feature code."}, 'toponymName': {'type': 'string', 'description': "GeoNames' main name for the feature, often the local-language form."}, 'featureClass': {'type': 'string', 'description': 'One-letter feature class (L area, A admin division, P populated place, â\x80¦).'}}, 'description': 'One level of the chain.', 'additionalProperties': False}, 'description': 'Administrative ancestors, Earth first and the requested feature last; empty when found is false. Levels a feature does not sit under are skipped.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['username_required', 'caller_account_rejected', 'server_account_rejected', 'quota_exhausted', 'upstream_rejected_parameter'], 'description': "Machine-readable failure mode. Declared by this tool: `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."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'found': {'type': 'boolean', 'description': 'False when GeoNames has no feature with this geonameId.'}, 'guidance': {'type': 'string', 'description': 'What to do next; present only when found is false.'}, 'geonameId': {'type': 'number', 'description': 'The geonameId that was requested.'}}, 'additionalProperties': False}

{'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, a positive integer up to 2147483647 such as 5809844 (Seattle), as returned in geonameId by the other geonames tools. A geonames.org/<id> URL is reduced to its id.'}, '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 or a comma-separated string. Case-insensitive; a tag also matches its regional forms (zh matches zh, zh-CN, and 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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['found']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['username_required', 'caller_account_rejected', 'server_account_rejected', 'quota_exhausted', 'upstream_rejected_parameter'], 'description': "Machine-readable failure mode. Declared by this tool: `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."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'found': {'type': 'boolean', 'description': 'False when GeoNames has no feature with this geonameId.'}, 'place': {'type': 'object', 'required': ['geonameId', 'name', 'toponymName', 'adminLevels', 'alternateNames', 'postalCodes', 'links', 'identifiers'], 'properties': {'lat': {'type': 'number', 'description': 'Latitude in decimal degrees. Absent when GeoNames sent none.'}, 'lng': {'type': 'number', 'description': 'Longitude in decimal degrees. Absent when GeoNames sent none.'}, 'name': {'type': 'string', 'description': 'Name of the place, as GeoNames displays it.'}, 'links': {'type': 'array', 'items': {'type': 'string', 'description': 'A URL.'}, 'description': 'Web pages GeoNames links to the place, as received.'}, 'timezone': {'type': 'object', 'properties': {'timezoneId': {'type': 'string', 'description': 'IANA timezone id, such as Europe/Paris.'}, 'dstOffsetInHours': {'type': 'number', 'description': 'UTC offset in hours on 1 July.'}, 'gmtOffsetInHours': {'type': 'number', 'description': 'UTC offset in hours on 1 January.'}}, 'description': 'Timezone of the place. Absent when GeoNames sends none.', 'additionalProperties': False}, 'asciiName': {'type': 'string', 'description': 'The name in plain ASCII characters.'}, 'geonameId': {'type': 'number', 'description': 'GeoNames feature id.'}, 'iso3166_2': {'type': 'string', 'description': 'ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO.'}, 'population': {'type': 'number', 'description': 'Population. Absent when GeoNames records none.'}, 'adminLevels': {'type': 'array', 'items': {'type': 'object', 'required': ['level'], 'properties': {'code': {'type': 'string', 'description': "The division's GeoNames admin code."}, 'name': {'type': 'string', 'description': "The division's name."}, 'level': {'type': 'number', 'description': 'Admin level, 1 (state, province) through 5.'}, 'geonameId': {'type': 'number', 'description': "The division's geonameId, where GeoNames gives one."}}, 'description': 'One admin division containing the place.', 'additionalProperties': False}, 'description': 'Admin divisions containing the place, first level first.'}, 'boundingBox': {'type': 'object', 'required': ['north', 'south', 'east', 'west'], 'properties': {'east': {'type': 'number', 'description': 'Eastern longitude bound, decimal degrees.'}, 'west': {'type': 'number', 'description': 'Western longitude bound, decimal degrees.'}, 'north': {'type': 'number', 'description': 'Northern latitude bound, decimal degrees.'}, 'south': {'type': 'number', 'description': 'Southern latitude bound, decimal degrees.'}}, 'description': 'Bounding box of the feature. Absent for most points.', 'additionalProperties': False}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 code of the containing country.'}, 'countryName': {'type': 'string', 'description': 'Name of the containing country.'}, 'featureCode': {'type': 'string', 'description': 'Feature code, such as PPLC (capital) or ADM1 (first-order division).'}, 'featureName': {'type': 'string', 'description': "GeoNames' name for the feature code."}, 'identifiers': {'type': 'array', 'items': {'type': 'object', 'required': ['type', 'value'], 'properties': {'type': {'enum': ['iata', 'icao', 'faac', 'tcid', 'unlc', 'wkdt'], 'type': 'string', 'description': 'Identifier scheme: iata airport, icao airport, faac FAA airport, tcid Transport Canada airport, unlc UN/LOCODE, wkdt Wikidata.'}, 'value': {'type': 'string', 'description': 'The identifier.'}}, 'description': 'One external identifier.', 'additionalProperties': False}, 'description': 'External identifiers of the place.'}, 'postalCodes': {'type': 'array', 'items': {'type': 'string', 'description': 'A postal code.'}, 'description': 'Postal codes GeoNames links to the place.'}, 'toponymName': {'type': 'string', 'description': "GeoNames' main name for the feature, often the local-language form."}, 'featureClass': {'type': 'string', 'description': 'One-letter feature class (P populated place, A admin division, â\x80¦).'}, 'wikipediaUrl': {'type': 'string', 'description': 'English Wikipedia article, as GeoNames sends it (without a scheme).'}, 'continentCode': {'type': 'string', 'description': 'Continent code: AF, AN, AS, EU, NA, OC, or SA.'}, 'alternateNames': {'type': 'array', 'items': {'type': 'object', 'required': ['name'], 'properties': {'lang': {'type': 'string', 'description': 'ISO 639 language tag, or a GeoNames pseudo-language: abbr abbreviation, phon phonetic, piny pinyin, fr_1793 French Revolution name. Absent when untagged.'}, 'name': {'type': 'string', 'description': 'The alternate name.'}, 'isShortName': {'type': 'boolean', 'description': 'True when GeoNames marks this a short name.'}, 'isPreferredName': {'type': 'boolean', 'description': 'True when GeoNames marks this the preferred name in its language.'}}, 'description': 'One alternate name.', 'additionalProperties': False}, 'description': 'Names in other languages and forms, filtered by nameLanguages when given.'}, 'countryGeonameId': {'type': 'number', 'description': "The containing country's geonameId, for geonames_get_children or geonames_get_place."}, 'featureClassName': {'type': 'string', 'description': "GeoNames' label for the class."}, 'elevationInMeters': {'type': 'number', 'description': 'Recorded elevation in metres. Often absent.'}, 'demElevationInMeters': {'type': 'number', 'description': 'Elevation from the SRTM3 digital elevation model, in metres.'}}, 'description': 'The full record; absent when found is false.', 'additionalProperties': False}, 'guidance': {'type': 'string', 'description': 'What to do next; present only when found is false.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['topic'], 'properties': {'limit': {'type': 'integer', 'default': 100, 'maximum': 700, 'minimum': 1, 'description': 'Maximum entries to return, 1 to 700. 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). Case-insensitive.'}, '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). Case-insensitive.'}, '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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['topic', 'entries', 'totalCount', 'truncated', 'shown', 'cap']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['filter_not_applicable', 'username_required', 'caller_account_rejected', 'server_account_rejected', 'quota_exhausted', 'upstream_rejected_parameter'], 'description': "Machine-readable failure mode. Declared by this tool: `filter_not_applicable`: featureClass was given with a topic other than feature_codes. `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."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Entries returned on this page.'}, 'topic': {'enum': ['feature_classes', 'feature_codes', 'postal_countries'], 'type': 'string', 'description': 'The topic listed.'}, 'notice': {'type': 'string', 'description': 'Guidance when nothing matched, the offset is past the end, or more pages remain.'}, 'entries': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'name'], 'properties': {'code': {'type': 'string', 'description': 'Feature class letter, feature code without its class prefix (PPLC), or ISO 3166-1 alpha-2 country code.'}, 'name': {'type': 'string', 'description': "GeoNames' label: the class label, the feature code's name, or the country name."}, 'description': {'type': 'string', 'description': "The class's category and code count, or GeoNames' definition of the feature code. Absent where GeoNames gives none."}, 'featureClass': {'enum': ['A', 'H', 'L', 'P', 'R', 'S', 'T', 'U', 'V'], 'type': 'string', 'description': 'Topic feature_codes: the class the code belongs to.'}, 'maxPostalCode': {'type': 'string', 'description': 'Topic postal_countries: the highest postal code or prefix GeoNames holds.'}, 'minPostalCode': {'type': 'string', 'description': 'Topic postal_countries: the lowest postal code or prefix GeoNames holds.'}, 'postalCodeCount': {'type': 'number', 'description': 'Topic postal_countries: how many postal codes GeoNames holds for the country.'}}, 'description': 'One vocabulary entry.', 'additionalProperties': False}, 'description': 'Entries on this page, in GeoNames order.'}, 'truncated': {'type': 'boolean', 'description': 'True when more entries remain past this page.'}, 'nextOffset': {'type': 'number', 'description': 'Offset of the next page; absent on the last page.'}, 'totalCount': {'type': 'number', 'description': 'Entries matching the topic and filters, before paging.'}}, 'additionalProperties': False}

{'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': 50, 'minimum': 0, 'description': 'How many nearest places or features to list, 0 to 50. 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 or a comma-separated string. Case-insensitive; a class prefix (T.MT) 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. 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. 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. 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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['lat', 'lng', 'adminLevels', 'nearbyKind', 'nearby', 'truncated', 'shown', 'cap']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The nearbyLimit that was applied.'}, 'lat': {'type': 'number', 'description': 'The latitude that was looked up.'}, 'lng': {'type': 'number', 'description': 'The longitude that was looked up.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['unknown_feature_code', 'conflicting_filters', 'feature_filter_mismatch', 'username_required', 'caller_account_rejected', 'server_account_rejected', 'quota_exhausted', 'upstream_rejected_parameter'], 'description': "Machine-readable failure mode. Declared by this tool: `unknown_feature_code`: A featureCodes entry is not a GeoNames feature code. `conflicting_filters`: cities was combined with featureClasses or featureCodes. `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. GeoNames intersects the two lists, so those entries match nothing. `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."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'ocean': {'type': 'object', 'required': ['name'], 'properties': {'name': {'type': 'string', 'description': 'Name of the ocean or sea.'}, 'geonameId': {'type': 'number', 'description': 'GeoNames feature id of the water body. Absent when GeoNames has none.'}}, 'description': 'The ocean or sea at the point; present only when no country contains it or lies within coastalBufferKm.', 'additionalProperties': False}, 'shown': {'type': 'number', 'description': 'Nearby places or features returned.'}, 'nearby': {'type': 'array', 'items': {'type': 'object', 'required': ['geonameId', 'name', 'toponymName'], 'properties': {'lat': {'type': 'number', 'description': 'Latitude in decimal degrees. Absent when GeoNames sent none.'}, 'lng': {'type': 'number', 'description': 'Longitude in decimal degrees. Absent when GeoNames sent none.'}, 'name': {'type': 'string', 'description': 'Name of the place or feature, as GeoNames displays it.'}, 'geonameId': {'type': 'number', 'description': 'GeoNames feature id: pass it to geonames_get_place or geonames_get_hierarchy.'}, 'adminName1': {'type': 'string', 'description': 'Name of the first-order admin division containing it.'}, 'population': {'type': 'number', 'description': 'Population. Absent when GeoNames records none.'}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 code of the containing country.'}, 'featureCode': {'type': 'string', 'description': 'Feature code, such as PPL (populated place), PPLX (section), PPLH (historical place), or MT (mountain).'}, 'featureName': {'type': 'string', 'description': "GeoNames' name for the feature code."}, 'toponymName': {'type': 'string', 'description': "GeoNames' main name for the feature, often the local-language form."}, 'distanceInKm': {'type': 'number', 'description': 'Distance from the point in kilometres. Absent when GeoNames sent no usable value.'}, 'featureClass': {'type': 'string', 'description': 'One-letter feature class (P populated place, T terrain, H water, â\x80¦).'}}, 'description': 'One nearby place or feature.', 'additionalProperties': False}, 'description': 'Nearest places or features, nearest first; empty when nearbyKind is none.'}, 'notice': {'type': 'string', 'description': 'Guidance when the point is offshore or unmapped, its country was matched within coastalBufferKm, nothing is nearby, nearby is full, or no IANA timezone covers it.'}, 'country': {'type': 'object', 'required': ['countryCode'], 'properties': {'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 country code.'}, 'countryName': {'type': 'string', 'description': 'Country name. Absent when GeoNames sent none.'}, 'distanceInKm': {'type': 'number', 'description': 'Kilometres from the point to this country as GeoNames maps it, to the metre. Present only when no country contains the point and this one was matched within coastalBufferKm.'}}, 'description': 'The country containing the point, or with coastalBufferKm the nearest country within that distance (then distanceInKm is set); absent offshore and in unmapped areas.', 'additionalProperties': False}, 'timezone': {'type': 'object', 'required': ['rawOffsetInHours', 'gmtOffsetInHours', 'dstOffsetInHours'], 'properties': {'sunset': {'type': 'string', 'description': "Today's local sunset, YYYY-MM-DD HH:mm. Absent offshore."}, 'sunrise': {'type': 'string', 'description': "Today's local sunrise, YYYY-MM-DD HH:mm. Absent offshore."}, 'localTime': {'type': 'string', 'description': 'Current local time, YYYY-MM-DD HH:mm. Absent offshore.'}, 'timezoneId': {'type': 'string', 'description': 'IANA timezone id, such as Europe/Paris. Absent offshore.'}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 code of the timezone country. Absent offshore.'}, 'dstOffsetInHours': {'type': 'number', 'description': "UTC offset in hours on 1 July. Without a timezoneId the offsets are GeoNames' open-water estimate, which has no DST, so this equals rawOffsetInHours."}, 'gmtOffsetInHours': {'type': 'number', 'description': 'UTC offset in hours on 1 January.'}, 'rawOffsetInHours': {'type': 'number', 'description': 'Standard UTC offset in hours, without DST.'}}, 'description': 'The timezone at the point; present only with includeTimezone.', 'additionalProperties': False}, 'truncated': {'type': 'boolean', 'description': 'True when nearby is full at nearbyLimit, so more may lie within the radius.'}, 'nearbyKind': {'enum': ['populated_places', 'features', 'none'], 'type': 'string', 'description': 'What nearby lists: populated_places, features (featureClasses or featureCodes was set), or none (nearbyLimit 0).'}, 'adminLevels': {'type': 'array', 'items': {'type': 'object', 'required': ['level'], 'properties': {'code': {'type': 'string', 'description': 'Admin code at this level.'}, 'name': {'type': 'string', 'description': 'Name of the division.'}, 'level': {'type': 'number', 'description': 'Admin level: 1 for the first-order division, up to 5.'}, 'isoCode': {'type': 'string', 'description': 'ISO 3166-2 code of the division, subdivision part only (IDF, not FR-IDF), where one exists.'}, 'geonameId': {'type': 'number', 'description': 'GeoNames feature id of the division: pass it to geonames_get_place.'}}, 'description': 'One admin division containing the point, or for a country matched within coastalBufferKm, the one nearest it.', 'additionalProperties': False}, 'description': 'Admin divisions containing the point, first level first; for a country matched within coastalBufferKm, the divisions of its part nearest the point. Empty offshore, and where GeoNames records no subdivision of the country.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'limit': {'type': 'integer', 'default': 10, 'maximum': 100, 'minimum': 1, 'description': 'Maximum entries to return, 1 to 100. 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. Case-insensitive.'}, '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. Case-insensitive."}, '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 (GeoNames' default) or population, largest first. Case-insensitive."}, '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 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.'}, '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 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."}, '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. 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.'}, '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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['places', 'totalCount', 'effectiveQuery', 'truncated', 'shown', 'cap']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['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'], 'description': "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."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Places returned on this page.'}, 'notice': {'type': 'string', 'description': 'Guidance when nothing matched or more pages remain.'}, 'places': {'type': 'array', 'items': {'type': 'object', 'required': ['geonameId', 'name', 'toponymName'], 'properties': {'lat': {'type': 'number', 'description': 'Latitude in decimal degrees. Absent when GeoNames sent none.'}, 'lng': {'type': 'number', 'description': 'Longitude in decimal degrees. Absent when GeoNames sent none.'}, 'name': {'type': 'string', 'description': 'Name of the place, as GeoNames displays it.'}, 'geonameId': {'type': 'number', 'description': 'GeoNames feature id: pass it to geonames_get_place, geonames_get_hierarchy, or geonames_get_children.'}, 'iso3166_2': {'type': 'string', 'description': 'ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO.'}, 'adminCode1': {'type': 'string', 'description': 'Code of the first-order admin division (state, province) containing it.'}, 'adminName1': {'type': 'string', 'description': 'Name of the first-order admin division containing it.'}, 'population': {'type': 'number', 'description': 'Population. Absent when GeoNames records none.'}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 code of the containing country.'}, 'countryName': {'type': 'string', 'description': 'Name of the containing country.'}, 'featureCode': {'type': 'string', 'description': 'Feature code, such as PPLC (capital) or ADM1 (first-order division).'}, 'featureName': {'type': 'string', 'description': "GeoNames' name for the feature code."}, 'toponymName': {'type': 'string', 'description': "GeoNames' main name for the feature, often the local-language form."}, 'featureClass': {'type': 'string', 'description': 'One-letter feature class (P populated place, A admin division, â\x80¦).'}, 'featureClassName': {'type': 'string', 'description': "GeoNames' label for the class."}}, 'description': 'One matching place.', 'additionalProperties': False}, 'description': 'Places on this page, in the requested order.'}, 'truncated': {'type': 'boolean', 'description': 'True when more matching places remain past this page.'}, 'nextOffset': {'type': 'number', 'description': "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': {'type': 'number', 'description': "GeoNames' count of matching places, before paging."}, 'effectiveQuery': {'type': 'string', 'description': 'The match mode, query, and filters as the server sent them to GeoNames.'}}, 'additionalProperties': False}