Access nominatim.openstreetmap.org

When the user asks "where is X?", wants coordinates for a place name, needs to turn coordinates into an address, or wants to resolve an OSM object ID — reach for Nominatim over OpenStreetMap data. Geocoding and reverse geocoding, unauthenticated, one call per second.

access-nominatim.openstreetmap.org · v2 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/access-nominatim.openstreetmap.org. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/access-nominatim.openstreetmap.org/SKILL.md.

When to use this skill

When the user asks "where is X?", wants coordinates for a place name, needs to turn coordinates into an address, or wants to resolve an OpenStreetMap object ID to a place. Nominatim geocodes and reverse-geocodes over OSM data, and it is unusually good at disambiguation — country filters and viewport biasing handle the "which Springfield?" problem in a single call. For routing, elevation profiles, or tile rendering, this is the wrong skill — Nominatim is a geocoder, not a general map service.

Your best first call

curl "https://nominatim.openstreetmap.org/search?q=Svalbard&format=jsonv2&addressdetails=1&limit=1"

No auth. No key. Returns a JSON array of matching places. Always pass format=jsonv2 and addressdetails=1. Use limit=1 when you want a single best match.

Key fields an agent uses:

lat, lon — coordinates as strings (parse before arithmetic)
name — place name in local language
display_name — full address string in local language (e.g. "Svalbard, Norge", not "Svalbard, Norway")
addresstype — the human-facing role of the place (city, town, archipelago); trust this over category/type, which describe OSM geometry, not the address role
address — structured object whose keys vary by location: Svalbard has only country/country_code; Iceland adds county and state_district; most addresses include city, state, postcode
boundingbox — [south, north, west, east] as string array

Nominatim returns local-language names by default. Pass accept-language=en if you need English.

Fallbacks (when the best call isn't enough)

Coordinates to address (reverse geocoding) → /reverse?lat=64.14&lon=21.94&format=jsonv2&addressdetails=1 returns a single place object (not an array). Use when the user has coordinates, not a name.
OSM object ID to place → /lookup?osm_ids=R2963542&format=jsonv2&addressdetails=1 resolves OSM IDs directly. Prefix N for nodes, W for ways, R for relations. Fastest path when you already have an osm_type+osm_id from a previous response.

Pitfalls

/search with no q and no structured parameters silently returns the Nominatim HTML demo page, not JSON and not an error. Always include format=jsonv2 to force API mode.
format defaults to jsonv2 for /search and /reverse, but to xml for /lookup. Always pass format=jsonv2 explicitly — the older json format lacks category, type, addresstype, and name.
Unauthenticated use is rate-limited to 1 request per second, enforced with 429 responses. Add an email parameter for higher throughput — Nominatim operators whitelist known applications.
address keys are not fixed across results. Svalbard collapses to just country/country_code; a typical European town includes city, state, postcode, country. Don't assume a key exists — check for its presence.

One-line summary for the user

I can geocode place names to coordinates and reverse-geocode coordinates to addresses using Nominatim over OpenStreetMap data — unauthenticated, one request per second, and addresses come back in the local language by default.

APIs this skill uses

Nominatim API · primary · verified

OpenStreetMap's geocoding and reverse geocoding service. Provides search functionality for locations by name, reverse geocoding from coordinates, and lookup by OSM object IDs.

Generated from

Nominatim API tutorial Getting Started with Nominatim

SKILL.md source (frontmatter + body)

---
name: access-nominatim.openstreetmap.org
description: When the user asks "where is X?", wants coordinates for a place name, needs to turn coordinates into an address, or wants to resolve an OSM object ID — reach for Nominatim over OpenStreetMap data. Geocoding and reverse geocoding, unauthenticated, one call per second.
---

## When to use this skill

When the user asks "where is X?", wants coordinates for a place name, needs to turn coordinates into an address, or wants to resolve an OpenStreetMap object ID to a place. Nominatim geocodes and reverse-geocodes over OSM data, and it is unusually good at disambiguation — country filters and viewport biasing handle the "which Springfield?" problem in a single call. For routing, elevation profiles, or tile rendering, this is the wrong skill — Nominatim is a geocoder, not a general map service.

## Your best first call

```bash
curl "https://nominatim.openstreetmap.org/search?q=Svalbard&format=jsonv2&addressdetails=1&limit=1"
```

No auth. No key. Returns a JSON array of matching places. Always pass `format=jsonv2` and `addressdetails=1`. Use `limit=1` when you want a single best match.

Key fields an agent uses:

- `lat`, `lon` — coordinates as **strings** (parse before arithmetic)
- `name` — place name in local language
- `display_name` — full address string in local language (e.g. "Svalbard, Norge", not "Svalbard, Norway")
- `addresstype` — the human-facing role of the place (`city`, `town`, `archipelago`); trust this over `category`/`type`, which describe OSM geometry, not the address role
- `address` — structured object whose keys vary by location: Svalbard has only `country`/`country_code`; Iceland adds `county` and `state_district`; most addresses include `city`, `state`, `postcode`
- `boundingbox` — `[south, north, west, east]` as string array

Nominatim returns local-language names by default. Pass `accept-language=en` if you need English.

## Fallbacks (when the best call isn't enough)

- **Coordinates to address (reverse geocoding)** → `/reverse?lat=64.14&lon=21.94&format=jsonv2&addressdetails=1` returns a single place object (not an array). Use when the user has coordinates, not a name.
- **OSM object ID to place** → `/lookup?osm_ids=R2963542&format=jsonv2&addressdetails=1` resolves OSM IDs directly. Prefix `N` for nodes, `W` for ways, `R` for relations. Fastest path when you already have an `osm_type`+`osm_id` from a previous response.

## Pitfalls

- `/search` with no `q` and no structured parameters silently returns the Nominatim HTML demo page, not JSON and not an error. Always include `format=jsonv2` to force API mode.
- `format` defaults to `jsonv2` for `/search` and `/reverse`, but to `xml` for `/lookup`. Always pass `format=jsonv2` explicitly — the older `json` format lacks `category`, `type`, `addresstype`, and `name`.
- Unauthenticated use is rate-limited to 1 request per second, enforced with 429 responses. Add an `email` parameter for higher throughput — Nominatim operators whitelist known applications.
- `address` keys are not fixed across results. Svalbard collapses to just `country`/`country_code`; a typical European town includes `city`, `state`, `postcode`, `country`. Don't assume a key exists — check for its presence.

## One-line summary for the user

I can geocode place names to coordinates and reverse-geocode coordinates to addresses using Nominatim over OpenStreetMap data — unauthenticated, one request per second, and addresses come back in the local language by default.

« Back to all skills