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

# Openstreetmap Nominatim Geocoding API

Nominatim is the official geocoding service for OpenStreetMap data. It provides forward geocoding (address or place name to coordinates), reverse geocoding (coordinates to nearest address), and address lookup by OSM object identifier. Because it is built on OpenStreetMap, coverage spans the entire world with the depth and freshness of the OSM community's edits. The public Nominatim instance at nominatim.openstreetmap.org enforces a usage policy of one request per second; teams with higher volume are expected to self-host or use a commercial provider.

## For AI agents

Geocode addresses to coordinates, reverse-geocode coordinates to addresses, and look up specific OpenStreetMap objects worldwide.

## Scope

Does not handle routing, traffic, or rendered map tiles - use for OpenStreetMap geocoding and address lookup only.

## Capabilities

- Geocode an address or place name to latitude and longitude using /search
- Reverse-geocode a lat/lng pair to the nearest address with /reverse
- Look up specific OpenStreetMap objects by OSM ID using /lookup
- Restrict search results by country code, bounding box, or feature type
- Inspect Nominatim server health and database freshness via /status

## Use cases

### Free Worldwide Address Geocoding

Convert user-entered addresses into latitude and longitude for storage, mapping, or distance calculations. Nominatim's /search endpoint accepts free-form queries or structured fields (street, city, postalcode, country) and returns scored matches with bounding boxes. It covers every country mapped in OpenStreetMap, making it useful for projects that need global coverage without per-request fees.

Example prompt: Call GET /search with q='Brandenburg Gate, Berlin' and format=json and return the first result's lat and lon

### Reverse Geocoding for Mobile Check-ins

Mobile applications that capture a user's GPS coordinates can call /reverse to display the nearest address or place name in the UI. Nominatim returns a structured address with hierarchy (road, suburb, city, country) plus a formatted display_name string suitable for direct rendering. This is common in delivery, ride-share, and field-service apps where the device knows the coordinates but the user wants a human-readable location.

Example prompt: Call GET /reverse with lat=37.7749, lon=-122.4194, format=json and return the display_name field

### OSM Object Lookup for Map Editors

When working with OpenStreetMap data dumps or building tools on top of OSM, you often need to resolve a list of OSM IDs to human-readable names and locations. The /lookup endpoint accepts up to 50 OSM type+ID pairs in a single request and returns enriched objects. This is more efficient than running separate /search calls and preserves OSM's canonical relationships between nodes, ways, and relations.

Example prompt: Call GET /lookup with osm_ids=N240109189,W43147938,R558775 and format=json to enrich a list of OSM references

### AI Agent Location Assistant

An AI agent answering 'where is X' or 'what's near coordinate Y' can use Nominatim through Jentic without hand-wiring an HTTP client or standing up its own geocoder. Jentic resolves the natural-language intent into the right /search or /reverse call and returns the response schema the agent needs. For higher volume the agent can be repointed at a self-hosted Nominatim with no agent-side change.

Example prompt: Through Jentic, search 'geocode an address' and execute against q='Eiffel Tower, Paris' to return coordinates

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /search | Forward geocode an address or place name |
| GET | /reverse | Reverse geocode coordinates to an address |
| GET | /lookup | Look up specific OSM objects by ID |
| GET | /status | Check Nominatim server status |

## Key resources

- **Search** — Forward geocoding - convert place names or addresses to coordinates.
- **Reverse** — Reverse geocoding - convert lat/lng to the nearest address.
- **Lookup** — Resolve a list of specific OSM type+ID pairs to enriched location records.
- **Status** — Check server availability and database freshness.

## Why Jentic

- **Setup:** Wiring Nominatim by hand means giving it a valid Referer or User-Agent identifying your application and pacing yourself to the public instance's one-request-per-second maximum so you are not blocked. Through Jentic you install once, import the Nominatim Geocoding API from the API Directory, and your agent calls it through your own self-hosted instance.
- **Permission scoping:** Nominatim is read-only geocoding with no credential, so scoping is by operation: you limit the agent to the operations it needs, such as search or reverse geocoding, and leave lookup or status out unless you want them. Every operation the agent can call is one you chose to allow.
- **Credential handling:** Nominatim needs no key, so no credential is stored for this API. Jentic still routes each call through the same audited execution path used for authenticated APIs, and nothing secret ever enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'geocode an address' or 'reverse geocode coordinates', and Jentic returns the matching Nominatim operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Geocodio API** — Commercial U.S. and Canada geocoding service with congressional district enrichment.
- **TomTom Maps API** — Commercial mapping platform with geocoding plus routing and traffic data.
- **Open States API v3** — Pair Nominatim's coordinates with Open States /people.geo to find a U.S. state legislator from an address.

## FAQ

### What authentication does the Nominatim Geocoding API use?

The public Nominatim instance does not require an API key, and the spec declares no security schemes for any of its 4 operations. The OpenStreetMap Foundation's Nominatim usage policy does require every caller to provide a valid HTTP Referer or User-Agent identifying the application, and states that stock User-Agents as set by HTTP libraries will not do.

### Can I geocode multiple addresses in one request with Nominatim?

The /search endpoint takes one query at a time, and the usage policy for the public instance rules out fanning out parallel requests: bulk tasks must be limited to a single thread on one machine, with no distributed scripts. Pace sequential calls under the absolute maximum of 1 request per second, or use /lookup, where up to 50 ids can be queried at the same time.

### What are the rate limits for the Nominatim Geocoding API?

The OpenStreetMap Foundation's Nominatim usage policy sets an absolute maximum of 1 request per second for the public nominatim.openstreetmap.org instance and rules out heavy uses. That ceiling is per website or application, not per user: the policy states the sum of traffic by all your users should not exceed the limits. Scripts running longer than a day and scripts that are run at regular intervals are restricted to 4 requests per minute, and results must be cached on your side. The policy also governs agent and LLM use directly, permitting an LLM to suggest the service only where it points to the policy and explains the restrictions, and it treats periodic requests from apps as bulk geocoding. For anything larger it directs you to a commercial third-party provider or to running your own Nominatim instance, which serves the same endpoints.

### How do I reverse-geocode a coordinate through Jentic?

Search Jentic for 'reverse geocode coordinates', load the GET /reverse schema, and execute with lat, lon, and format=json. Jentic returns the structured address response from Nominatim including the display_name string.

### Does Nominatim support routing or directions?

No - Nominatim is geocoding only. For routing on OpenStreetMap data use OSRM, GraphHopper, or Valhalla. For places search and points of interest, /search supports it but is not optimized for ranked POI discovery; consider Overpass API for richer POI queries.

### How fresh is the data in the Nominatim Geocoding API?

Nominatim's documentation publishes no update cadence for the public instance, so do not assume one. What it does document is a way to check: the /status endpoint returns a data_updated field reporting when the database was last updated, so read that timestamp before relying on a query.

### Is there a Nominatim MCP server?

You don't need an MCP server to give your agent Nominatim. Jentic connects it directly from the API Directory: import the Nominatim Geocoding API and your agent gets the full 4-endpoint surface, without loading another server's tool definitions into its context. Nominatim needs no API key, so you have nothing to store, and your own rules decide which of its operations the agent may call.

### Can I limit what my agent is allowed to do with the Nominatim Geocoding API?

Yes. Because you run Jentic One self-hosted, your own rules decide which Nominatim operations the agent may call. Since Nominatim is read-only geocoding with no credential to store, scoping is by operation: you can allow only search and reverse while leaving lookup and status unavailable, so the agent can geocode addresses and coordinates but nothing more. Every operation the agent can reach is one you chose to permit.