NewAnswers MCP: one question, one checked answer for your agent.See how it works

Guides

OpenStreetMap API: keys, Overpass, Nominatim, usage limits, Python and MCP

By , founder of HyperresearchPublished

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:

Terminal window
curl -A "MyApp/1.0 (+https://example.org)" \
https://api.openstreetmap.org/api/0.6/node/8600414155.json

That 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:

  1. Sign in at openstreetmap.org (or the test server master.apis.dev.openstreetmap.org, which is the place to try edits first).
  2. 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_prefs and write_api. Redirect URIs must be https, unless they start with http://127.0.0.1; for a script, use urn:ietf:wg:oauth:2.0:oob.
  3. Copy the client ID and client secret. The secret “cannot be shown again”.
  4. 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_api and copy the code it shows.
  5. Exchange the code at https://www.openstreetmap.org/oauth2/token:
Terminal window
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
  1. 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, formerly overpass.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=1

Always 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.

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") plus RateLimiter(geocode, min_delay_seconds=1). It raises ConfigurationError if you keep its default or a sample User-Agent such as my-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:

Terminal window
claude mcp add openstreetmap -e OSM_USER_AGENT="your-app/1.0 (you@example.org)" \
-- npx -y @cyanheads/openstreetmap-mcp-server

Claude 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