OpenStreetMap API: geocoding and routing on OSM data

OpenStreetMap has one API of its own, and it's for editing the map. Searching for an address, finding a route, and showing a map are separate services built on OpenStreetMap data, each with its own public server and usage policy. This guide covers which one does what, with an example request for each, and what to use when an app outgrows them.

Which service does what

None of them needs a key or an account to read. All of them are free, run by the OpenStreetMap Foundation or volunteers, with no guarantee of uptime. Each asks for a User-Agent header that names your app, since a library's default gets blocked, and each can block a client without notice if it affects other users.

The OpenStreetMap API

The OpenStreetMap API, version 0.6, is what editors such as iD and JOSM use to read and change the map. It returns raw map objects: nodes, which are points, ways, which are lines and outlines, and relations, which group them. Reading one is a single request:

curl -A "my-app/1.0" "https://api.openstreetmap.org/api/0.6/node/1.json"

Editing needs an OpenStreetMap account and OAuth 2.0, and groups changes into changesets. The API isn't meant for apps that only read: its usage policy allows at most two download threads, and points read-only users to Overpass, or to the full data in planet.osm.

Overpass: query map data

The Overpass API answers questions about the map's data, such as every cafe within 300 meters of a point. Queries are written in its own language, Overpass QL:

curl -A "my-app/1.0" https://overpass-api.de/api/interpreter --data-urlencode \
  'data=[out:json][timeout:25];node["amenity"="cafe"](around:300,45.5217,-122.6733);out;'

It returns each matching node with its coordinates and tags, such as name and opening_hours. Overpass Turbo is a page for writing and testing queries on a map.

The main public server asks users to stay under about 10,000 queries and 1 GB of data a day, and a hundredth of that for regular use. Its own page warns that it's often overloaded, so an app that depends on it should expect slow or failed queries.

Nominatim: geocoding

Nominatim is the geocoder behind the search box on openstreetmap.org. It turns an address or place name into coordinates, and coordinates into an address:

curl -A "my-app/1.0" "https://nominatim.openstreetmap.org/search?q=128+SW+3rd+Ave,+Portland&format=jsonv2&limit=1"

[
  {
    "osm_type": "way",
    "osm_id": 243085443,
    "lat": "45.5217396",
    "lon": "-122.6732913",
    "category": "amenity",
    "type": "cafe",
    "name": "Stumptown Coffee Roasters",
    "display_name": "Stumptown Coffee Roasters, 128, Southwest 3rd Avenue, Chinatown, Old Town, Portland, Multnomah County, Oregon, 97206, United States"
  }
]

The coordinates are strings, so convert them before doing math with them. /reverse?lat=…&lon=… finds the address at a point.

The public server's usage policy is the strictest of these services:

• At most one request a second, from your whole app, not each user.
• No autocomplete. Suggesting addresses as someone types is forbidden.
• Cache results on your side, and don't repeat the same query.
• Bulk geocoding is discouraged, and allowed only for small, one-off jobs from a single thread.

That fits a script or a low-traffic site. It doesn't fit an app whose users search for addresses directly.

OSRM: routing

OSRM is a routing engine for OpenStreetMap roads. FOSSGIS, the German OpenStreetMap group, runs public servers for driving, cycling, and walking, which the directions on openstreetmap.org use. This gets a walking route in Portland:

curl -A "my-app/1.0" "https://routing.openstreetmap.de/routed-foot/route/v1/foot/-122.6733,45.5217;-122.6801,45.5230?overview=false"

{
  "code": "Ok",
  "routes": [{ "distance": 686.4, "duration": 552.9, … }],
  …
}

Distances are in meters and times in seconds. Points go in the URL as longitude then latitude, the other way round from Nominatim's answers. For driving or cycling, use routed-car or routed-bike. With overview=full, the route's line comes back as an encoded polyline at precision 5, which decoding a route polyline explains.

The usage policy allows at most one request a second, with no heavy use or scraping, and the OSRM project's wiki limits the same servers to reasonable, non-commercial use.

Map tiles

The map on openstreetmap.org is drawn from image tiles at https://tile.openstreetmap.org/{z}/{x}/{y}.png, which Leaflet and other libraries can show. The tile usage policy requires:

• The OpenStreetMap credit, visible on the map.
• A User-Agent that names your app, and the page's Referer from a browser.
• Caching each tile for at least 7 days if you can't read the server's caching headers.

It forbids downloading tiles ahead of time, or for offline use, and says commercial services may lose access at any point. For offline maps, it points to vector tiles or hosting your own.

The license and credit

OpenStreetMap's data is licensed ODbL. Anything that shows it, such as a map, a route, or a geocoded address, has to credit "© OpenStreetMap contributors" with a link to that page.

You can store geocoding results and use them with your own data: OpenStreetMap's geocoding guideline treats single results as too small to bring in the share-alike terms. Collecting enough of them to rebuild a substantial part of the map would, and so would publishing a database built from OpenStreetMap data.

When an app outgrows the public servers

The public servers are generous for testing and light use, but their limits rule out autocomplete, steady traffic, and bulk work. There are two ways past them.

Run your own. Nominatim, OSRM, and the tile stack are open source, so you can run them with no limits. They need large servers for the whole planet: Nominatim needs 128 GB of memory and 1 TB of fast disk, and OSRM about 123 GB of memory for the car profile alone. Each also needs its data refreshed. Self-hosting Nominatim and self-hosting map tiles walk through two of them.

Use a hosted API built on OpenStreetMap. Mapricot is one. It runs geocoding, autocomplete, places, routing, and map tiles on OpenStreetMap and other open data, under one key:

The same address as the Nominatim example, from Mapricot:

curl "https://api.mapricot.com/v1/search?q=128+SW+3rd+Ave,+Portland&limit=1" \
  -H "Authorization: Bearer $MAPRICOT_KEY"

{  "attribution": [    {      "source": "openaddresses",      "text": "OpenAddresses",      "url": "https://openaddresses.io"    }  ],  "results": [    {      "id": "mp_b3BlbmFkZHJlc3NlczphZGRyZXNzOnVzL29yL211bHRub21haDpkZjdlYzM3YWJiYTJiNWM0",      "type": "address",      "name": "128 SW 3rd Avenue",      "label": "128 SW 3rd Avenue, Portland, OR, USA",      "lat": 45.521736,      "lon": -122.673276,      "address": {        "houseNumber": "128",        "street": "SW 3rd Avenue",        "postalCode": "97204",        "locality": "Portland",        "region": "Oregon",        "regionCode": "OR",        "country": "United States",        "countryCode": "US"      },      "source": "openaddresses"    }  ]}

Coordinates come back as numbers, and the address in parts under address. Addresses come from OpenAddresses and Overture as well as OpenStreetMap, for more house numbers. The first 250,000 requests every 30 days are free, then they cost $0.10 per 1,000, with no per-second limit to stay under. See pricing.

Questions

Is the OpenStreetMap API free? Yes. The data and every public server are free, with no key. The limit is the usage policies, not a price.

Does OpenStreetMap have an API key? No. Reading needs no account. The public servers tell apps apart by their User-Agent and Referer instead, which is why a missing or generic one gets blocked.

Can I use OpenStreetMap commercially? The data, yes, with the credit the ODbL requires. The public servers are a different matter: the tile and editing policies say commercial services can lose access at any time, and the OSRM servers are for non-commercial use. Commercial apps usually run their own servers or pay for a hosted API.

Can I use Nominatim for address autocomplete? No. The public server's policy forbids it, and its policy notes that Nominatim doesn't support autocomplete. Address autocomplete in JavaScript builds it on Mapricot's autocomplete instead.