GeoNames API

Name: GeoNames API
Brand: GeoNames API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentMaps GeolocationGeocodingapiKey18 EndpointsREST

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.

Jentic One on Github View OpenAPI Document

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.

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

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 instance

Jentic 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

GET STARTED

Start building with GeoNames API

Explore with Jentic One

View OpenAPI Document

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.

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.