canonical: https://jentic.com/apis/geonames.org/geonames

# GeoNames API

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.

## For AI agents

Look up postal codes, place names, country and subdivision data, timezones, and elevation worldwide using the GeoNames geographical database.

## Scope

Does not handle routing, turn-by-turn directions, or street-level address geocoding - use for place-name, postal-code, timezone, and elevation lookups only.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: Search Jentic for 'find nearest place name', execute /findNearbyPlaceNameJSON with the user-supplied coordinate, and return the place name, country, and population

## Key endpoints

| 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 |

## Key resources

- **Postal Codes** — Search and look up postal codes worldwide with place-name context
- **Places** — Find nearby place names for a coordinate
- **Countries** — Retrieve country info, codes, and subdivisions for a coordinate or ISO code
- **Timezones** — Resolve a coordinate to its IANA timezone and current offset
- **Elevation** — Query SRTM1, SRTM3, and ASTER GDEM elevation for a coordinate
- **Ocean / Neighbourhood** — Detect ocean coordinates and resolve neighbourhood names within US cities

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **OpenCage** — Worldwide forward and reverse geocoding aggregating multiple open data sources
- **Positionstack** — Forward and reverse geocoding API with bulk and single-request modes
- **HERE Maps** — Routing, traffic, and map tiles to pair with GeoNames' place and timezone data

## FAQ

### 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.