Integration examples

Copy-paste examples that match the live API. Each one handles the empty-result and error cases, which are the parts most tutorials skip.

JavaScript (browser or Node 18+)

async function geocode(q) {
  const url = new URL("https://opengeocoder.net/api/v1/geocode");
  url.searchParams.set("q", q);
  url.searchParams.set("limit", "1");
  const res = await fetch(url);
  const body = await res.json();
  if (!res.ok) throw new Error(body.error?.message ?? `HTTP ${res.status}`);
  return body.results[0] ?? null;        // null = no match (not an error)
}

const place = await geocode("Utrecht");
if (place) console.log(place.lat, place.lon, place.bbox); // bbox = [W, S, E, N]

Python

import requests

def reverse(lat, lon, zoom=18):
    r = requests.get(
        "https://opengeocoder.net/api/v1/reverse",
        params={"lat": lat, "lon": lon, "zoom": zoom},
        headers={"User-Agent": "my-app/1.0 (you@example.com)"},
        timeout=15,
    )
    if r.status_code == 429:
        raise RuntimeError(f"Rate limited; retry after {r.headers.get('Retry-After')} s")
    r.raise_for_status()
    return r.json()["result"]   # None when nothing is mapped nearby

print(reverse(25.1972, 55.2742)["display_name"])

Fit a Leaflet map to a result

Leaflet wants [[south, west], [north, east]], which is not the API's [west, south, east, north]. Convert explicitly:

const [w, s, e, n] = place.bbox;
map.fitBounds([[s, w], [n, e < w ? e + 360 : e]]); // handle antimeridian boxes
L.marker([place.lat, place.lon]).addTo(map);
map.attributionControl.addAttribution("Geocoding © OpenStreetMap contributors");

curl

curl -s "https://opengeocoder.net/api/v1/search?q=Springfield&countrycodes=us&limit=5"
curl -s "https://opengeocoder.net/api/0.1/search?query=Tempe,%20AZ"
curl -s -o opengeocoder-2012.json "https://opengeocoder.net/api/0.1/dump"

Caching and retries

  • Store what you geocode, together with the source, licence and date. Re-geocoding the same address every page view is slow and wasteful.
  • Retry only on 429, 502 and 503, honouring Retry-After, and with exponential backoff. Never retry a 400: the request itself is wrong.
  • Treat an empty results array as a normal outcome. Ask the user to refine the address instead of guessing.

Licensing checklist

  • Live results are OpenStreetMap data under the ODbL 1.0. Display “© OpenStreetMap contributors” with a link to openstreetmap.org/copyright.
  • If you build and publish a database from many geocoding results, the ODbL's share-alike terms may apply to it. Read the OSMF's geocoding guideline.
  • 2012 archive records are public domain; no attribution is required, though a link back is appreciated.

Full reference: API documentation. Background: how to use a geocoding API and OpenStreetMap geocoding basics.