API documentation

Base URL https://opengeocoder.net. All endpoints use GET, return UTF-8 JSON and send Access-Control-Allow-Origin: *.

Conventions

  • Coordinates are WGS84 decimal degrees. Points are returned as separate lat and lon fields.
  • Every bounding box (bbox) is [west, south, east, north], the GeoJSON order. Note that this differs from Nominatim's own boundingbox order. 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 carry source: "opengeocoder-2012-archive" and are public domain.

GET /api/v1/geocode

Forward geocoding: text in, ranked candidates out.

ParameterRequiredDescription
qyesAddress or place, 2–300 characters
limitno1–10, default 5
countrycodesnoComma-separated ISO 3166-1 alpha-2 codes, e.g. ae,om
langnoPreferred language for names, e.g. en, ar, de. Default en
viewboxnowest,south,east,north — prefer results inside this box
boundedno1 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.

FieldMeaning
lat, lonRepresentative point of the matched feature
bbox[west, south, east, north] extent of the feature
category, type, addresstypeOpenStreetMap feature class and type, and the address level the feature represents (house, road, suburb, city…)
place_rankNominatim's 0–30 rank, from continent (low) to house (30)
importance0–1 prominence estimate used for ranking
addressStructured address components (keys vary by country)
osmSource object type, id and link
cachedtrue if served from our 7-day cache

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

ParameterRequiredDescription
lat, lonyesDecimal degrees
zoomnoLevel of detail, 3 (country) to 18 (building). Default 18
langnoPreferred 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

HTTPerror.codeWhen
400missing_query, invalid_limit, invalid_coordinates, invalid_viewbox…A parameter is missing or out of range; error.message says which
404not_foundUnknown endpoint
429rate_limitedMore than ~30 requests a minute from your network; see Retry-After
502upstream_unavailableThe geocoding source failed; no result was generated
503busy, upstream_rate_limitedThe 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.