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.

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://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | 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

GET STARTED

Start building with GeoNames API

Explore with Jentic

View OpenAPI Document

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.

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 the Jentic vault 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

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

GeoNames usernames live in the Jentic vault encrypted with the customer-scoped key. Jentic injects the username as the query parameter at execution time, so even though the credential is sent in the URL, it never enters the agent's context or appears in logs.

Intent-based discovery

Agents search by intent ('find nearby place name', 'get timezone for a coordinate') and Jentic returns the matching GeoNames operation with its parameter schema, so the agent calls the right endpoint without parsing GeoNames' export documentation.

Time to first call

Direct GeoNames integration: a few hours to wrap the auth pattern and the JSON response shapes across the endpoints you need. Through Jentic: under 30 minutes to call any of the 18 operations from an agent.

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 at https://app.jentic.com/sign-up.

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.