Nominatim (OpenStreetMap) API
Free OpenStreetMap geocoding API: convert addresses to coordinates and back. No API key, open data, 1 request per second. Tested curl example and usage policy.
Endpoint tested and returned HTTP 200 on 2026-08-19
What is the Nominatim (OpenStreetMap) API?
Nominatim is the free geocoding API behind OpenStreetMap. It converts addresses and place names into coordinates, and coordinates back into addresses, using open data with no API key — subject to a strict limit of one request per second.
Nominatim is the reference implementation of geocoding over OpenStreetMap data, and it is the only widely available free API that does both forward and reverse geocoding at full street-address detail without a key.
Its usage policy is unusually strict and genuinely enforced: a maximum of one request per second, a required User-Agent or Referer identifying your application, and no bulk geocoding. Ignoring these gets your IP blocked quickly. For anything at volume, self-host Nominatim — the software is open source.
Quick facts
- Base URL
https://nominatim.openstreetmap.org- Authentication
- No key, but you MUST send a User-Agent identifying your application. Requests with a generic or absent User-Agent are blocked.
- Rate limit
- Maximum 1 request per second, strictly enforced. Bulk geocoding is forbidden on the public instance.
- Pricing
- Free, ODbL-licensed open data. Attribution to OpenStreetMap contributors is required when displaying results.
- CORS
- Not enabled — call it from your server
- Official docs
- Read the docs
How to use the Nominatim (OpenStreetMap) API
Every request below was executed against the live API on 2026-08-19, and the response shown is the real body it returned — not an illustration.
1. Geocode a city name to coordinates
GET https://nominatim.openstreetmap.org/search?q=Lahore&format=json&limit=1
curl 'https://nominatim.openstreetmap.org/search?q=Lahore&format=json&limit=1'const res = await fetch("https://nominatim.openstreetmap.org/search?q=Lahore&format=json&limit=1");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://nominatim.openstreetmap.org/search?q=Lahore&format=json&limit=1", timeout=20)
res.raise_for_status()
print(res.json())[
{
"place_id": 245974082,
"licence": "Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
"osm_type": "node",
"osm_id": 1886594378,
"lat": "31.5656822",
"lon": "74.3141829",
"class": "place",
"type": "city",
"place_rank": 16,
"importance": 0.6560037220993477,
"addresstype": "city",
"name": "لاہور",
"display_name": "لاہور, تحصیل لاہور شہر, ضلع لاہور, لاہور ڈویژن, پنجاب, 54100, پاکستان",
"boundingbox": [
"31.4056822",
"31.7256822",
"74.1541829",
"74.4741829"
]
}
]Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Required | Free-form search query, for forward geocoding. Lahore |
format | string | Required | Output format — use `json` or `jsonv2`. json |
limit | integer | Optional | Maximum number of results. Defaults to 10. 1 |
addressdetails | integer | Optional | Set to 1 to include a broken-down address object. 1 |
countrycodes | string | Optional | Comma-separated ISO codes to restrict the search. pk |
Response fields
lat / lonstring- Coordinates as strings, not numbers — parse before doing arithmetic.
display_namestring- Full human-readable address of the match.
type / classstring- OSM classification, e.g. class `place` type `city`.
importancefloat- Relevance score used to rank results.
boundingboxarray- Four strings giving the bounding box, handy for setting map zoom.
What you can build with the Nominatim (OpenStreetMap) API
- Convert a user-entered address into map coordinates
- Reverse geocode GPS coordinates into a street address via the /reverse endpoint
- Fit a map viewport to a search result using the returned bounding box
- Validate and normalise addresses at signup without a paid geocoder
Common errors and how to fix them
403
Blocked for policy violation — usually a missing or generic User-Agent, or exceeding 1 req/sec.
Fix: Send a real User-Agent naming your app and contact address, and throttle to one request per second.
429
Too many requests.
Fix: Add a hard client-side throttle. If you need volume, self-host Nominatim.
Empty array
No match found; not an error.
Fix: Loosen the query or drop `countrycodes`, and handle the empty case in code.
Nominatim (OpenStreetMap) API — frequently asked questions
Is Nominatim free to use?
Yes, it is free and built on OpenStreetMap open data with no API key. The public instance enforces a hard limit of one request per second and requires a descriptive User-Agent identifying your application.
Can I use Nominatim for bulk geocoding?
Not on the public instance — bulk geocoding is explicitly prohibited and will get your IP blocked. Nominatim is open source, so self-host it if you need to process addresses at volume.
Does Nominatim support reverse geocoding?
Yes. Call the /reverse endpoint with `lat` and `lon` parameters to turn coordinates into a structured street address.
Why are lat and lon returned as strings?
Nominatim returns coordinates as JSON strings to preserve exact precision. Convert with parseFloat or equivalent before doing any calculation, or you will end up concatenating instead of adding.
Tools that pair with this API
JSON Formatter
Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.
Unit Converter
Convert between units of length, weight, temperature, area, volume, speed, time and data storage instantly, with a swap button and common conversion tables.
Nominatim (OpenStreetMap) is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-19; always check the official documentation before relying on this API in production, as terms and limits can change.