Conventions
- Coordinates are WGS84 decimal degrees. Points are returned as separate
latandlonfields. - Every bounding box (
bbox) is [west, south, east, north], the GeoJSON order. Note that this differs from Nominatim's ownboundingboxorder. If west is greater than east, the box crosses the 180° meridian. - Live results carry
source: "openstreetmap-nominatim"and the ODbL attribution. 2012 archive results carrysource: "opengeocoder-2012-archive"and are public domain.
GET /api/v1/geocode
Forward geocoding: text in, ranked candidates out.
| Parameter | Required | Description |
|---|---|---|
q | yes | Address or place, 2–300 characters |
limit | no | 1–10, default 5 |
countrycodes | no | Comma-separated ISO 3166-1 alpha-2 codes, e.g. ae,om |
lang | no | Preferred language for names, e.g. en, ar, de. Default en |
viewbox | no | west,south,east,north — prefer results inside this box |
bounded | no | 1 to return only results inside viewbox |
GET /api/v1/geocode?q=Utrecht&limit=1
{
"query": "Utrecht",
"count": 1,
"results": [
{
"lat": 52.0907,
"lon": 5.1214,
"display_name": "Utrecht, Nederland",
"name": "Utrecht",
"bbox": [4.9705, 52.0263, 5.1950, 52.1427],
"category": "boundary",
"type": "administrative",
"addresstype": "city",
"place_rank": 16,
"importance": 0.7,
"address": { "city": "Utrecht", "state": "Utrecht", "country": "Nederland", "country_code": "nl" },
"osm": { "type": "relation", "id": 1433619, "url": "https://www.openstreetmap.org/relation/1433619" },
"source": "openstreetmap-nominatim"
}
],
"attribution": "Data © OpenStreetMap contributors, available under the Open Database License (ODbL 1.0). …",
"licence": "ODbL-1.0",
"cached": false
}
Values above are illustrative of the shape; the live response reflects current OpenStreetMap data.
| Field | Meaning |
|---|---|
lat, lon | Representative point of the matched feature |
bbox | [west, south, east, north] extent of the feature |
category, type, addresstype | OpenStreetMap feature class and type, and the address level the feature represents (house, road, suburb, city…) |
place_rank | Nominatim's 0–30 rank, from continent (low) to house (30) |
importance | 0–1 prominence estimate used for ranking |
address | Structured address components (keys vary by country) |
osm | Source object type, id and link |
cached | true if served from our 7-day cache |
GET /api/v1/search
Same parameters as geocode. The default limit is 10. The response adds an archive array of up to five matching records from the 2012 dataset: { id, q, bbox, source, licence }. Use it to disambiguate shared names.
GET /api/v1/reverse
| Parameter | Required | Description |
|---|---|---|
lat, lon | yes | Decimal degrees |
zoom | no | Level of detail, 3 (country) to 18 (building). Default 18 |
lang | no | Preferred language |
GET /api/v1/reverse?lat=52.0907&lon=5.1214&zoom=18
{
"query": { "lat": 52.0907, "lon": 5.1214, "zoom": 18 },
"result": { "lat": …, "lon": …, "display_name": "…", "bbox": [ … ], "address": { … }, "source": "openstreetmap-nominatim" },
"attribution": "…",
"licence": "ODbL-1.0",
"cached": false
}
result is null when nothing is mapped near the point, for example at sea. Coordinates are rounded to five decimal places (about 1 m) before lookup.
GET /api/v1/archive
Case-insensitive substring search of the 2012 archive. Parameters: q (required, at least 2 characters) and limit (1–50, default 20). Returns { query, count, total_records, results: [{ id, q, bbox }], source, licence }. Served entirely from our own copy of the archive; no upstream request.
Legacy API (2012): /api/0.1/search and /api/0.1/dump
The original endpoints still answer at their original addresses, so 2012-era links and code keep working.
GET /api/0.1/search?query=Redmond,%20Washington returns a JSON array, as the original did. Matching is exact on the lower-cased string, and synonyms resolve to their parent record, again as in the original.
[
{
"id": 16,
"q": "redmond, washington",
"querystring": "redmond, washington",
"bbox": [-122.1140082, 47.6626473, -122.1091144, 47.666967],
"matched_via": "query",
"source": "opengeocoder-2012-archive",
"licence": "Public domain (OpenGeocoder 2012 archive)"
}
]
Both q (the April 2012 dump's field name) and querystring (the February 2012 name) are included, so either generation of client code finds what it expects. The search response itself was never captured by the Internet Archive, so we built this shape from the archived dumps. Treat it as a faithful reconstruction, not a byte-for-byte copy.
If the archive has no match, the endpoint falls back to a single live OpenStreetMap result in the same shape, with id: null, extra lat, lon and display_name fields, source: "openstreetmap-nominatim" and its ODbL licence. If nothing matches anywhere, it returns [].
When a browser asks for HTML, the legacy search URL shows a readable page with the same data on a map. Add &format=json to force JSON. API clients that send Accept: application/json or */* always get JSON.
GET /api/0.1/dump returns { queries: [{ id, q, bbox }], synonyms: [{ id, qid, q }], about: { … } }. That is the April 2012 format plus a provenance block. About 160 KB.
Errors
| HTTP | error.code | When |
|---|---|---|
| 400 | missing_query, invalid_limit, invalid_coordinates, invalid_viewbox… | A parameter is missing or out of range; error.message says which |
| 404 | not_found | Unknown endpoint |
| 429 | rate_limited | More than ~30 requests a minute from your network; see Retry-After |
| 502 | upstream_unavailable | The geocoding source failed; no result was generated |
| 503 | busy, upstream_rate_limited | The shared queue is full; retry after Retry-After seconds |
{ "error": { "code": "invalid_limit", "message": "`limit` must be an integer from 1 to 10." } }
Fair use
Cache responses on your side. Send one request per user action, not one per keystroke: autocomplete is not supported. Don't use the API for bulk or scheduled batch jobs. Show “© OpenStreetMap contributors” next to any live results you display. We may block clients that ignore these rules, so that the service stays usable for everyone and within OpenStreetMap's usage policy.