Guides
OpenStreetMap API: keys, Overpass, Nominatim, usage limits, Python and MCP
OpenStreetMap has no API key and no price list: its services are free, run on donated servers, and are rationed by usage policies instead of keys. The thing called “the OpenStreetMap API” (api.openstreetmap.org/api/0.6) is the editing API, and its policy says it is “not for read-only purposes”. To read map data, query the Overpass API; to turn addresses into coordinates, use Nominatim at no more than one request per second; for whole countries or the planet, download the data files.
Every limit, endpoint and quote below was read from the OpenStreetMap Foundation’s operations policies, the OSM wiki and the Overpass and Nominatim documentation on November 15, 2026, and the response bodies were recorded from live requests that day.
OpenStreetMap services and endpoints
OpenStreetMap is not one API but a set of services that share the same data. Pick by job:
| Service | Endpoint | Use it for | Auth | Main limit (Nov 2026) |
|---|---|---|---|---|
| Editing API v0.6 | https://api.openstreetmap.org/api/0.6/ |
Editing the map; reading single elements and their history | None to read, OAuth 2.0 to write | Not for read-only projects; 0.25 square degree bbox; 2 download threads |
| Overpass API | https://overpass-api.de/api/interpreter |
Reading filtered data: every cafe in a box, every road in a city | None | About 10,000 queries and 1 GB a day for one-off use, a hundredth of that for regular jobs |
| Nominatim | https://nominatim.openstreetmap.org/search and /reverse |
Geocoding and reverse geocoding | None | 1 request per second, identifying User-Agent, no bulk or autocomplete |
| Standard tiles | https://tile.openstreetmap.org/{z}/{x}/{y}.png |
Showing the map on a page or app | None | Identifying User-Agent, cache 7 days, no prefetch or offline |
| Planet and extracts | https://planet.openstreetmap.org/ |
All data, or a country or state | None | Weekly planet PBF is 89 GB |
The editing API’s usage policy says it “is provided in order to edit the map data, not for read-only purposes or projects” and that “large or frequent data users must use the download service” or the alternatives it lists, which are the planet files and Overpass. Read requests to it need no authorization, so it works for fetching one known element:
curl -A "MyApp/1.0 (+https://example.org)" \ https://api.openstreetmap.org/api/0.6/node/8600414155.jsonThat call returns the node’s coordinates, tags, version, changeset and editor. The server’s own limits are published at /api/0.6/capabilities.json; on November 15, 2026 it reported a maximum map area of 0.25 square degrees, 2,000 nodes per way, 10,000 elements per changeset and a 300-second timeout.
OpenStreetMap API keys and OAuth 2.0 tokens
No OpenStreetMap service issues API keys. Overpass, Nominatim, the tiles and reads from the editing API work anonymously; what they ask for instead is a User-Agent that names your application. The only credential in OpenStreetMap is an OAuth 2.0 access token, and you need one only to write: create a changeset, edit, upload GPS traces or read the logged-in user’s details.
OAuth 1.0a and HTTP Basic Auth were shut down in June 2024, per the API v0.6 wiki. To get an OAuth 2.0 token, from the OAuth wiki page:
- Sign in at openstreetmap.org (or the test server
master.apis.dev.openstreetmap.org, which is the place to try edits first). - Open your account settings and the OAuth 2 applications link, then register an application: a name, redirect URIs and the scopes you need, such as
read_prefsandwrite_api. Redirect URIs must behttps, unless they start withhttp://127.0.0.1; for a script, useurn:ietf:wg:oauth:2.0:oob. - Copy the client ID and client secret. The secret “cannot be shown again”.
- Send the user to
https://www.openstreetmap.org/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=read_prefs%20write_apiand copy the code it shows. - Exchange the code at
https://www.openstreetmap.org/oauth2/token:
curl -X POST https://www.openstreetmap.org/oauth2/token \ -d grant_type=authorization_code \ -d code=YOUR_AUTHORIZATION_CODE \ -d redirect_uri=urn:ietf:wg:oauth:2.0:oob \ -d client_id=YOUR_CLIENT_ID \ -d client_secret=YOUR_CLIENT_SECRET- Send the token as
Authorization: Bearer YOUR_ACCESS_TOKEN. The wiki says access tokens “currently do not expire automatically”.
Pages that tell you to “get an OpenStreetMap API key” are describing a commercial tile or geocoding service built on OSM data, a forum’s own user key, or a plugin’s settings screen. None of those is an OSM credential.
OpenStreetMap API pricing and usage limits
The OpenStreetMap Foundation charges nothing for any of these services and sells no paid tier. The price is following the usage policies, and each one says access can be withdrawn without notice. The planet download page asks for voluntary donations: $50 to $100 a year from individuals, $250 to $1,000 from small and medium organizations, and corporate membership for larger businesses.
| Service | Documented limit | Source |
|---|---|---|
| Nominatim | “An absolute maximum of 1 request per second”; scripts that run longer than a day or on a schedule: 4 requests per minute | Nominatim Usage Policy |
| Overpass, overpass-api.de | Under 10,000 queries and 1 GB a day, and under 10 minutes of total run time, for one-off use; divide by 100 (100 queries, 10 MB) for anything regular | Overpass wiki |
| Overpass, per query | Default timeout 180 seconds and memory 512 MiB, raised with [timeout:] and [maxsize:] |
Overpass manual |
| Editing API | Valid User-Agent, maximum 2 download threads, 0.25 square degree map calls, no more than 50,000 nodes per map call | API policy, API v0.6 |
| Tiles | Identifying User-Agent, Referer from web pages, cache at least 7 days, no bulk download or offline features | Tile Usage Policy |
For an app or website, the limits apply to the sum of all your users’ traffic, not to each user. That is the line most tutorials skip.
Reading OSM data with the Overpass API
Overpass is the read-only query service for OpenStreetMap data. You POST a query in Overpass QL to /api/interpreter as a form field named data, and it returns JSON, XML or CSV. This query returns every cafe in a bounding box, with a center point for cafes mapped as buildings:
[out:json][timeout:60];nwr["amenity"="cafe"](48.19,-114.33,48.21,-114.30);out center tags;The parts: [out:json] sets the format; [timeout:60] declares the run time; nwr means nodes, ways and relations; ["amenity"="cafe"] is a tag filter; the four numbers are south, west, north and east, which is the opposite order from the editing API’s bbox=left,bottom,right,top; out center tags prints tags plus one coordinate per object. Run on November 15, 2026, it returned 12 cafes. Build and test queries in the browser at overpass-turbo.eu before you script them.
Public instances. The OSM wiki list names three with worldwide data:
overpass-api.de, the main instance run by FOSSGIS: two servers, the limits in the table above, no parallel scripts, and “Commercial use should use self-hosted or paid Overpass servers.” The wiki also says “Nowadays this server is overloaded” and asks users not to expect high reliability. The same rules ban “platforms for fast-deployment of AI-generated apps”.overpass.private.coffee, formerlyoverpass.kumi.systems, which says there is “no rate limit in place” and asks to be told before large-scale use.- A mirror hosted in Russia, at
maps.mail.ru/osm/tools/overpass/api/interpreter, which states no request limits.
How the rate limit works. The Overpass manual identifies each user by IP address and gives each a few slots; each query holds a slot for its run time plus a cool-down that grows with server load. GET https://overpass-api.de/api/status shows yours: on November 15, 2026 it read “Rate limit: 2” and “2 slots available now.” A request with no free slot waits up to 15 seconds and is then refused with HTTP 429. A second check admits a query only if its declared timeout and memory fit in half of what the server has left; a refused query gets HTTP 504. Smaller [timeout:] and [maxsize:] values get admitted sooner.
Results lag the main database by a few minutes. Every response carries osm3s.timestamp_osm_base, the time of the data it was answered from.
Geocoding with the Nominatim API
Nominatim turns a place name or address into coordinates (/search) and coordinates into an address (/reverse). A search call looks like this:
https://nominatim.openstreetmap.org/search?q=Kalispell,+Montana&format=jsonv2&limit=1Always send format: on the OSM-run server, a request without it is forwarded to the web interface instead of returning data. limit defaults to 10 and caps at 40, and countrycodes, viewbox with bounded=1, addressdetails=1 and accept-language narrow or enrich results, per the Search docs (Nominatim 5.3.3). Each result carries a licence field: “Data © OpenStreetMap contributors, ODbL 1.0.”
The Nominatim Usage Policy sets the rules for the public server:
- Rate: “an absolute maximum of 1 request per second”, summed across all users of your app.
- Identification: a User-Agent or Referer naming your application; “stock User-Agents as set by http libraries will not do”.
- Bulk: discouraged. A small one-time job is allowed on one thread and one machine, with results cached; scripts that run more than a day or on a schedule are held to 4 requests per minute.
- Banned: client-side autocomplete, systematic queries (“reverse queries in a grid”, lists of postcodes, “downloading all POIs in an area”), scraping the details page, and reselling results.
- AI tools: “LLMs may only suggest this service, if they prominently point to this usage policy and explain the restrictions of use to the user.” Code they generate must follow the policy, and the public API “must not be built into” no-code, low-code or vibe-coding platforms as a generic geocoder.
For thousands of addresses or anything recurring, the policy points to running your own Nominatim or using a third-party provider. For “all the cafes in a city”, use Overpass, not Nominatim.
Map tiles from tile.openstreetmap.org
The standard map tiles are free to view but not to harvest. The Tile Usage Policy requires the exact URL https://tile.openstreetmap.org/{z}/{x}/{y}.png, visible attribution, a User-Agent that identifies your app, a Referer from web pages, and caching for at least 7 days if your client cannot read the cache headers. It forbids bulk downloading, prefetch and “download for offline” features, and says traffic with library-default User-Agents such as python-requests/x.y “will be blocked”. Vector tiles at vector.openstreetmap.org have a separate policy. For heavy or offline use, host your own tiles or use a provider that allows it.
Bulk OSM data: planet files and extracts
For a whole country, state or the planet, download a file instead of querying. planet.openstreetmap.org publishes a full copy every week; on November 15, 2026 the planet PBF was 89 GB and the XML 168 GB, with minutely diffs to stay current. The page links two providers of free country and state extracts, Geofabrik (download.geofabrik.de) and BBBike. Read PBF files in Python with osmium (pyosmium 4.3.2, October 2026), or load them into PostGIS with osm2pgsql. Both the Overpass manual and the Nominatim policy send anyone who wants every feature in a large area to these files.
Python: Overpass cafes in a bounding box and a Nominatim search
This script uses only requests. It identifies itself, pauses on Overpass 429 and 504 as the wiki asks, catches a query that ran out of time, and spaces and caches Nominatim calls at one per second. It ran on November 15, 2026 and printed the geocoded town and 12 cafes.
import time
import requests
# Both services require a User-Agent that names your application.# Library defaults such as "python-requests/2.x" are blocked.HEADERS = {"User-Agent": "MyCafeMap/1.0 (+https://example.org; maps@example.org)"}OVERPASS_URL = "https://overpass-api.de/api/interpreter"NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
def overpass(query, retries=3): """POST one Overpass QL query and return the parsed JSON.""" for attempt in range(retries): resp = requests.post(OVERPASS_URL, data={"data": query}, headers=HEADERS, timeout=200) if resp.status_code in (429, 504): # 429: no free slot for your IP. 504: server too busy to admit it. time.sleep(30 * (attempt + 1)) continue if resp.status_code == 400: raise ValueError(f"Overpass QL error: {resp.text[:500]}") resp.raise_for_status() data = resp.json() # A query that hits its own [timeout] still returns HTTP 200, # with the error in "remark" and a partial element list. if "runtime error" in data.get("remark", ""): raise RuntimeError(data["remark"]) return data raise RuntimeError("Overpass busy; try later or use another instance")
def cafes_in_bbox(south, west, north, east): """Every node, way and relation tagged amenity=cafe in a bounding box.""" query = f""" [out:json][timeout:60]; nwr["amenity"="cafe"]({south},{west},{north},{east}); out center tags; """ rows = [] for el in overpass(query)["elements"]: point = el if el["type"] == "node" else el.get("center", {}) tags = el.get("tags", {}) rows.append({ "osm": f"{el['type']}/{el['id']}", "name": tags.get("name"), "lat": point.get("lat"), "lon": point.get("lon"), "opening_hours": tags.get("opening_hours"), }) return rows
_last_call = 0.0_cache = {}
def geocode(text): """Nominatim search, cached, never faster than one request per second.""" global _last_call if text in _cache: return _cache[text] wait = 1.0 - (time.monotonic() - _last_call) if wait > 0: time.sleep(wait) resp = requests.get(NOMINATIM_URL, headers=HEADERS, timeout=30, params={"q": text, "format": "jsonv2", "limit": 1}) _last_call = time.monotonic() resp.raise_for_status() results = resp.json() _cache[text] = results[0] if results else None return _cache[text]
if __name__ == "__main__": place = geocode("Kalispell, Montana") print(place["display_name"], place["lat"], place["lon"]) for cafe in cafes_in_bbox(48.19, -114.33, 48.21, -114.30): print(cafe) print("Data (c) OpenStreetMap contributors, ODbL")Replace the User-Agent with your own app name and contact before you run it. Libraries that do the same work:
- geopy (2.5.0, July 2026):
Nominatim(user_agent="your-app")plusRateLimiter(geocode, min_delay_seconds=1). It raisesConfigurationErrorif you keep its default or a sample User-Agent such asmy-application. - overpy (0.7, December 2023): parses Overpass results into Python objects. It has not had a release in nearly three years.
- OSMnx (2.1.2, November 14, 2026): downloads street networks, buildings and points of interest by place name or bounding box through Overpass and Nominatim, into GeoDataFrames and graphs.
OpenStreetMap API errors and real response bodies
The bodies marked “observed” were returned on November 15, 2026; the others are quoted from the OSM docs, wiki and forums.
| Status and body | Service | Cause | Fix |
|---|---|---|---|
400, HTML page “OSM3S Response” with Error: line 1: parse error: ']' expected - '(' found. (observed) |
Overpass | Overpass QL syntax error | Test the query in overpass turbo; the body names the line |
429, Dispatcher_Client::request_read_and_idx::rate_limited. Please check /api/status for the quota of your IP address. |
Overpass | No free slot for your IP | Wait 30 seconds or more; check /api/status; never run scripts in parallel |
504, Error: runtime error: open64: 0 Success /osm3s_osm_base Dispatcher_Client::request_read_and_idx::timeout. |
Overpass | Server could not admit the query’s declared time and memory | Lower [timeout:] and [maxsize:], split the area, retry later or use another instance |
200 with "remark": "runtime error: Query timed out in \"query\" at line ... after N seconds." |
Overpass | Query exceeded its own [timeout:]; the elements are partial |
Raise [timeout:] or shrink the area; always check remark |
400, The maximum bbox size is 0.250000, and your request was too large. Either request a smaller area, or use planet.osm (observed, text/plain, also in an Error: header) |
Editing API | /map call larger than 0.25 square degrees |
Use Overpass or an extract |
| 400 | Editing API | /map call would return more than 50,000 nodes |
Smaller box, or Overpass |
401, Couldn't authenticate you (observed, text/plain) |
Editing API | Write call without a valid OAuth 2.0 token | Add Authorization: Bearer YOUR_ACCESS_TOKEN |
509, Error: You have downloaded too much data. Please try again later. |
Editing API | Download volume over the limit | Stop reading through the editing API; use Overpass or planet files |
| 403 or 429 | Nominatim, tiles | Default library User-Agent, over 1 request per second, or a blocked pattern | Set an identifying User-Agent, slow down and cache; geopy warns of exactly these codes |
| Blank page or HTML instead of JSON | Nominatim | format missing, so the request went to the web interface |
Add format=jsonv2 |
OpenStreetMap MCP servers for Claude, Cursor and ChatGPT
The OpenStreetMap Foundation publishes no official MCP server, and a search of the official MCP registry on November 15, 2026 for “openstreetmap”, “overpass” and “nominatim” returned no entry from OSM. The open-source servers call the same public Nominatim and Overpass instances, so the usage policies above apply to everything your assistant does through them, summed across every user of the same server.
| Repository | Stars, last push (Nov 15, 2026) | Language and license | Tools | Notes |
|---|---|---|---|---|
| cyanheads/openstreetmap-mcp-server | 9, Nov 13, 2026 | TypeScript, Apache-2.0 | 6: search places, reverse geocode, look up objects, query nearby, query bbox or boundary, raw Overpass QL | Spaces Nominatim calls 1,050 ms apart, one Overpass query at a time, OSM_USER_AGENT setting, ODbL attribution on every response; in the MCP registry |
| jagan-shanmugam/open-streetmap-mcp | 235, Jul 12, 2025 | Python, MIT | 12, including geocode, nearby places, routes, meeting point, EV charging, neighborhood analysis | uvx osm-mcp-server (PyPI 0.1.1, May 2025); one fixed User-Agent for all users; routes via the public OSRM demo server |
| NERVsystems/osmmcp | 32, Oct 8, 2026 | Go, MIT | 20+, including geocoding, bbox queries, OSRM routes, polylines, map images | Pre-built binaries |
| wiseman/osm-mcp | 91, Mar 13, 2025 | Python, no license file | Map viewer control plus SQL on your own PostGIS copy of OSM | For self-hosted data |
Claude Code, running the cyanheads server locally:
claude mcp add openstreetmap -e OSM_USER_AGENT="your-app/1.0 (you@example.org)" \ -- npx -y @cyanheads/openstreetmap-mcp-serverClaude Desktop (claude_desktop_config.json, in %APPDATA%\Claude\ on Windows or ~/Library/Application Support/Claude/ on macOS) and Cursor (~/.cursor/mcp.json or .cursor/mcp.json) take the same entry:
{ "mcpServers": { "openstreetmap": { "command": "npx", "args": ["-y", "@cyanheads/openstreetmap-mcp-server"], "env": { "OSM_USER_AGENT": "your-app/1.0 (you@example.org)" } } }}For the Python server, use "command": "uvx", "args": ["osm-mcp-server"]. Point OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL at your own instances for heavy use.
ChatGPT connects only to remote servers over SSE or streaming HTTP: go to Plugins, the plus button, Add custom MCP server (OpenAI’s guide). The cyanheads project runs a public endpoint at https://openstreetmap.caseyjhand.com/mcp with no authentication, which answered an MCP initialize call on November 15, 2026. It is also the quickest route for Claude Code: claude mcp add --transport http openstreetmap https://openstreetmap.caseyjhand.com/mcp. A shared endpoint sends every user’s requests to Nominatim and Overpass under one identity, so for anything beyond light use, run the server yourself or host it with your own User-Agent.
ODbL license and attribution
OpenStreetMap data is licensed under the Open Database License (ODbL) 1.0. The copyright page sums it up: you may copy, distribute and adapt the data “as long as you credit OpenStreetMap and its contributors”, and if you alter or build on it, you may distribute the result only under the same license. In practice:
- Maps and apps: show “© OpenStreetMap contributors” (or “© OpenStreetMap”) where people see the map, with “OpenStreetMap” linked to openstreetmap.org/copyright. The Attribution Guidelines, adopted June 25, 2021, require it to be visible without clicking and readable.
- Internal use: attribution is required only when a produced work is used publicly.
- Databases you share: a derivative database must carry OSM attribution and the ODbL text or a link, and be offered under the ODbL.
- Geocoding results: a group of results need not carry attribution as long as it does not form a derivative database.
- Machine learning: a training set that is a substantial extraction of OSM is a derivative database if used publicly; a model’s predictions are not covered, unless the model can recreate substantial parts of the data.
Choosing a route for OpenStreetMap data
- Every feature of one kind in a city or region (cafes, schools, roads): Overpass, with a declared
[timeout:], one query at a time. - A country, a state or the planet, or a regular refresh: planet files or an extract, read with osmium or loaded into PostGIS.
- Geocoding a few addresses a user typed: public Nominatim at 1 request per second, cached. Thousands of addresses, recurring jobs or autocomplete: your own Nominatim or a commercial geocoder.
- A map on a website: the standard tiles with attribution and normal browser caching. Offline or high-traffic apps: your own tiles or a tile provider.
- Editing the map: the v0.6 API with an OAuth 2.0 token, tested on the dev server first.
- An AI assistant that looks up places: an open-source MCP server run locally with your own
OSM_USER_AGENT. - Cited business counts next to other data: Hyperresearch reads OpenStreetMap for mapped businesses near a point, as a floor for competitor counts, as one of its 120+ data sources.
For other public data APIs, see the Census API and FRED API in Python guides; for more servers an assistant can use, see MCP servers for research data.
Sources
- API Usage Policy (editing API): https://operations.osmfoundation.org/policies/api/
- Nominatim Usage Policy: https://operations.osmfoundation.org/policies/nominatim/
- Tile Usage Policy: https://operations.osmfoundation.org/policies/tiles/
- API v0.6 (OSM wiki): https://wiki.openstreetmap.org/wiki/API_v0.6
- OAuth (OSM wiki): https://wiki.openstreetmap.org/wiki/OAuth
- Overpass API and public instances (OSM wiki): https://wiki.openstreetmap.org/wiki/Overpass_API
- Overpass API status reports (OSM wiki): https://wiki.openstreetmap.org/wiki/Overpass_API/status
- Overpass API User’s Manual, Commons: https://dev.overpass-api.de/overpass-doc/en/preface/commons.html
- Nominatim Search API (5.3.3): https://nominatim.org/release-docs/latest/api/Search/
- Copyright and License: https://www.openstreetmap.org/copyright
- Licence/Attribution Guidelines: https://osmfoundation.org/wiki/Licence/Attribution_Guidelines
- Planet OSM: https://planet.openstreetmap.org/
- geopy Nominatim source: https://github.com/geopy/geopy/blob/master/geopy/geocoders/nominatim.py
- Official MCP registry: https://registry.modelcontextprotocol.io
- OpenAI, Add custom MCP server: https://developers.openai.com/api/docs/guides/developer-mode
