GeoNames API
Agent-ready OpenAPI document · curated by JenticMaps GeolocationGeocodingapiKey18 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Look up postal codes, place names, country and subdivision data, timezones, and elevation worldwide using the GeoNames geographical database.
Use for: I need to find the postal code for 'Berlin Mitte', Get the country for coordinate 35.6762, 139.6503, Retrieve the timezone for a lat/lng pair, Find the nearest place name to a hiking trail coordinate
Not supported: Does not handle routing, turn-by-turn directions, or street-level address geocoding - use for place-name, postal-code, timezone, and elevation lookups only.
Jentic publishes the only available OpenAPI specification for GeoNames API, keeping it validated and agent-ready. GeoNames is a worldwide geographical database web service offering postal-code search, place-name lookup, country and subdivision data, neighbourhood resolution, ocean and timezone lookups, and digital-elevation queries (SRTM1, SRTM3, ASTER GDEM). The 18 JSON endpoints are widely used as a free or low-cost alternative to commercial geocoders for global place-name and postcode resolution. Authentication is by username, attached as a query parameter on every request.
Install Jentic One Beta
Connect the GeoNames API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the GeoNames API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgeonames.org%2Fgeonames" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgeonames.org%2Fgeonames" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with GeoNames API.
Search global postal codes by code or place name with /postalCodeSearchJSON
Find the nearest place name for a coordinate with /findNearbyPlaceNameJSON
Resolve a coordinate to a country or country subdivision with /countryCodeJSON
Retrieve timezone information for a coordinate with /timezoneJSON
Pull SRTM1, SRTM3, or ASTER GDEM elevation values for a coordinate
Detect whether a coordinate is over an ocean using /oceanJSON
Use Cases
Patterns agents use GeoNames API for, with concrete tasks.
★ Worldwide Postcode Resolution
Logistics and e-commerce platforms operating globally need to validate or resolve postal codes across dozens of countries without subscribing to a commercial geocoder. GeoNames' /postalCodeSearchJSON and /postalCodeLookupJSON endpoints return matching postcodes and their place names, letting checkout flows confirm that a code exists and belongs to the expected country.
Call /postalCodeSearchJSON for the user-entered postcode and country code, then confirm at least one match before allowing checkout to proceed
Outdoor App Elevation Lookup
Hiking, cycling, and trail-mapping apps annotate routes with elevation values along the path. /srtm3JSON and /astergdemJSON return elevation readings for a given coordinate, so an app can produce an elevation profile for a route by sampling points without packaging gigabytes of DEM data on-device.
For each waypoint on the user's GPX route, call /srtm3JSON and append the elevation reading to build a route elevation profile
Timezone-Aware Scheduling
Scheduling tools booking events between participants in different countries need a reliable coordinate-to-timezone lookup. /timezoneJSON returns the IANA timezone name and current offset for a given lat/lng, so a calendar event can be stored in the correct local time without depending on a third-party geocoder.
Call /timezoneJSON for a meeting venue's lat/lng and store the returned IANA zone on the calendar event
AI Agent Geographic Reasoning
An AI agent answering geographic questions can ground its replies in GeoNames' structured data via Jentic. The agent searches for 'find nearby place name' or 'get country for a coordinate', loads the matching schema, and executes the call. The username is held in your Jentic One instance and attached as the query parameter at the edge.
Search Jentic for 'find nearest place name', execute /findNearbyPlaceNameJSON with the user-supplied coordinate, and return the place name, country, and population
Key Endpoints
18 endpoints — jentic publishes the only available openapi specification for geonames api, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
GET
/postalCodeSearchJSON
Search postal codes by code or place name
GET
/postalCodeLookupJSON
Look up a specific postal code
GET
/findNearbyPlaceNameJSON
Find the nearest place name for a coordinate
GET
/countryCodeJSON
Resolve a coordinate to a country code
GET
/countryInfoJSON
Retrieve country metadata by ISO code
GET
/timezoneJSON
Resolve a coordinate to its IANA timezone
GET
/srtm3JSON
Retrieve SRTM3 elevation for a coordinate
GET
/oceanJSON
Identify whether a coordinate is over an ocean
GET
/postalCodeSearchJSON
Search postal codes by code or place name
GET
/postalCodeLookupJSON
Look up a specific postal code
GET
/findNearbyPlaceNameJSON
Find the nearest place name for a coordinate
GET
/countryCodeJSON
Resolve a coordinate to a country code
GET
/countryInfoJSON
Retrieve country metadata by ISO code
GET
/timezoneJSON
Resolve a coordinate to its IANA timezone
GET
/srtm3JSON
Retrieve SRTM3 elevation for a coordinate
GET
/oceanJSON
Identify whether a coordinate is over an ocean
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the GeoNames API by hand means registering your username, appending it as a query parameter on every request, and routing postal-code, place-name, timezone, and elevation calls to the right endpoints yourself. Through Jentic you install once, import GeoNames from the API Directory, store the username once, and your agent calls it.
Permission scoping
GeoNames' lookups like /findNearbyPlaceNameJSON and /timezoneJSON take their input in the query string rather than the URL path, so scope the agent to the operations it needs, such as nearby place-name and timezone lookups. You choose the operations it may call, so lookups like elevation or ocean data are not included unless you add them.
Credential isolation
Your GeoNames username is stored once, encrypted, by your own Jentic One instance and injected as the query parameter at execution time. Even though it travels in the URL, it never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'find a nearby place name' or 'get the timezone for a coordinate', and Jentic returns the matching GeoNames operation with its parameter schema so the agent calls the right endpoint without parsing the export documentation.
Related APIs
Alternatives and complements available in the Jentic catalogue.
Alternative
Positionstack
Forward and reverse geocoding API with bulk and single-request modes
Choose Positionstack for street-address-level geocoding when GeoNames' place-name granularity is too coarse
FAQs
Specific to using GeoNames API through Jentic.
Why is there no official OpenAPI spec for GeoNames API?
GeoNames documents its web services on its export pages but does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call GeoNames API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.
What authentication does the GeoNames API use?
GeoNames authenticates by username - pass it as the username query parameter on every request. Through Jentic the username is stored in the vault and injected at execution time, so an agent calling /findNearbyPlaceNameJSON never sees the raw value.
Can I look up postal codes worldwide with this API?
Yes. /postalCodeSearchJSON searches by free-text place name or partial code, and /postalCodeLookupJSON resolves a specific code. Both accept a country filter so you can scope the lookup to a single country when you know the context.
Does GeoNames return elevation data?
Yes. /srtm1JSON, /srtm3JSON, and /astergdemJSON each return elevation for a coordinate from the corresponding global digital-elevation model. Pick the dataset that matches your resolution needs - SRTM1 for higher resolution, ASTER for higher latitude coverage.
What are the rate limits for the GeoNames API?
GeoNames meters by daily and hourly request counts per username, with the free tier allowing a few thousand calls per day. Production workloads should register a paid premium account on geonames.org and avoid tight polling - batch lookups and cache results per coordinate or postcode.
How do I find the timezone for a coordinate through Jentic?
Run pip install jentic, search Jentic for 'get timezone for a coordinate', and call /timezoneJSON with the lat and lng parameters. The response includes the IANA timezone name and the current GMT and DST offsets.
Is the GeoNames API free?
GeoNames is free for low-volume use with a registered username and offers paid premium accounts for higher quotas and faster servers. Sign up at geonames.org for the free tier and upgrade if your daily lookup volume exceeds the free allowance.
Can I limit what my agent is allowed to do with the GeoNames API?
Yes. Because you run Jentic One yourself, your own rules decide which GeoNames operations your agent may call, so you can allow only nearby place-name lookups with /findNearbyPlaceNameJSON and timezone lookups with /timezoneJSON while excluding others. Elevation queries like /srtm3JSON or ocean checks with /oceanJSON stay unavailable to the agent unless you add them. Your GeoNames username is held by your own instance and attached as the query parameter at execution time, so the agent never sees the raw credential.
GET STARTED