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,502and503, honouringRetry-After, and with exponential backoff. Never retry a400: the request itself is wrong. - Treat an empty
resultsarray 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.