Search for how to use the OpenStreetMap API and you will find tutorials quietly describing four different services as if they were one. They are not, and the difference is not pedantry: send a geocoding question to the editing API and you get raw XML and confusion; hammer the tile servers like an API and you get blocked; ignore Nominatim's usage policy and your requests start failing without explanation. The good news is that each service is simple once it has its own name. This guide gives the four services their names, their jobs, and their rules, then puts three working first requests in your hands.
Home / GIS and Open Map Data for Beginners
How to Use the OpenStreetMap API: Four Services, Three First Requests, Zero Blocks

Photo: Daniil Komov / Pexels
Coordinate Explorer: Read Off the Corners for Your First Request
Your first bounding box read needs four numbers: the left, bottom, right, and top edges. Click the top-left and bottom-right corners of your area here and copy the exact coordinates your request asks for.
Map data © OpenStreetMap contributors. Coordinates are read from the map itself, in the WGS 84 system your phone uses.
The Four Services, Decoded
| Service | Its one job | Key needed | The rule that matters |
|---|---|---|---|
| Editing API (API 0.6) | Read and write the raw map database itself | No key to read; OAuth 2.0 to write | Small areas only; it serves editors, not bulk extraction |
| Nominatim | Geocoding: names to coordinates, coordinates to addresses | No key | One request per second, a real identifying User-Agent, no autocomplete |
| Overpass API | Ask questions of the data: "all cafes within 500 meters of this point" | No key | Sensible timeouts and sizes; it is a shared public computer |
| Tile servers | Serve finished map pictures to browsing humans | No key | No bulk downloading, no scraping; heavy use gets blocked |
Every beginner task belongs to exactly one row. Finding the coordinates of a named place: Nominatim. Extracting features for a project: Overpass. Reading one small area's raw data exactly as editors see it: the editing API's map call. Drawing a map on your website: tiles, under their policy, or better, a tile provider. Our guide to using OpenStreetMap covers the human side of the project; this article is the machine side.
First Request One: Read Raw Map Data (Editing API)
The map call asks the editing API for everything inside a rectangle, in the database's own XML format:
```
https://api.openstreetmap.org/api/0.6/map?bbox=-73.9965,40.7505,-73.9755,40.7685
```
The bbox parameter is four numbers in a strict order: left (minimum longitude), bottom (minimum latitude), right (maximum longitude), top (maximum latitude). Longitude before latitude here, the reverse of the usual pair order, and a classic first error. The box must be small, at most 0.25 square degrees, because this endpoint exists so editors can load a neighborhood, not so anyone can drain the database. The response is the raw material of the map: nodes with coordinates, ways referencing nodes, relations grouping ways, all carrying the tags our open map database guide takes apart. Paste the URL into a browser and you are reading the database itself, which is a genuinely thrilling first request.
First Request Two: Geocode a Name (Nominatim)
Nominatim answers "where is this place" with structured data:
```
https://nominatim.openstreetmap.org/search?q=Statue+of+Liberty&format=json&limit=1
```
Add parameters for what you need: format=json for machine readable output, limit to cap results, addressdetails=1 to break the address into parts. Two policy rules are load bearing. First, one request per second, maximum: this is a free community service, and the limit is the price. Second, send a real User-Agent identifying your application; requests from default library agents get refused, by design. And one functional rule: Nominatim is not an autocomplete engine, so do not call it per keystroke; call it when the user submits a search.
First Request Three: Ask a Question (Overpass), From Python
Overpass speaks a query language, and its party trick is the radius question. This query finds every cafe within 500 meters of Times Square:
```
[out:json][timeout:25];
node"amenity"="cafe";
out body;
```
Send it to the interpreter endpoint, https://overpass-api.de/api/interpreter, as a POST with the query in a field named data. From Python, the whole conversation, for both this and a Nominatim lookup, fits on one screen:
```python
import requests
# Nominatim: name to coordinates. Identify yourself, stay under 1 request/second.
headers = {"User-Agent": "my-first-map-project/1.0 (me@example.com)"}
r = requests.get(
"https://nominatim.openstreetmap.org/search",
params={"q": "Statue of Liberty", "format": "json", "limit": 1},
headers=headers,
)
place = r.json()[0]
print(place["lat"], place["lon"])
# Overpass: every cafe within 500 m of Times Square.
query = """
[out:json][timeout:25];
node"amenity"="cafe";
out body;
"""
r = requests.post(
"https://overpass-api.de/api/interpreter",
data={"data": query},
headers=headers,
)
cafes = r.json()["elements"]
print(len(cafes), "cafes found")
```
That script is a complete, honest first program against the open map: it identifies itself, respects the rate limit, and asks a question with a real answer. Everything else is elaboration.

The Rules That Keep You Welcome (and Unblocked)
The OpenStreetMap infrastructure is donated and community run, and its policies are the terms of a gift, not obstacles to route around. Identify yourself with a real User-Agent or application name everywhere. Respect rate limits: one per second on Nominatim, sensible pacing on Overpass, and never parallel hammering. Cache: if your app geocodes the same address twice, the second answer should come from your own storage, not from Nominatim. Never bulk download tiles: if you need map pictures at scale, use a tile provider or render your own from downloaded data; our OpenStreetMap download guide covers the legitimate bulk routes, planet files and regional extracts, which exist precisely so the APIs do not have to serve as firehoses. Attribute: results carry the credit "© OpenStreetMap contributors" and the ODbL license terms for the data. And when a response says 403 or 429, read it as the service protecting itself, back off, and check your pacing and your User-Agent before retrying; the failure table below decodes the common ones.
| Symptom | Likely cause | Fix |
|---|---|---|
| 403 Forbidden from Nominatim | Default or missing User-Agent | Send a real User-Agent naming your app |
| 429 or slowing responses | Rate limit exceeded | Slow to one request per second; cache results |
| Empty result from the map call | Bbox order wrong, or box too large | Order is left, bottom, right, top; keep the box small |
| Overpass timeout | Query too wide or no timeout set | Add [timeout:25]; shrink the area; filter earlier |
| Blocked after tile scraping | Bulk tile downloading | Switch to a tile provider or downloaded data |
Writing Data: The Door With a Lock, Correctly
Everything above reads. Writing, actually editing the map through the API, is a different world: it requires an OpenStreetMap account, OAuth 2.0 authentication, and changesets, the versioned edit sessions editors work in. It is beyond a first requests guide, and deliberately so: the read services are where applications live, and the write path is where cartographers live. If your project idea involves correcting the map itself, the honest route is a proper editor like iD, and our open map data explainer covers the license that governs what you may do with everything you have read. The beginner's milestone is the three requests above, running, identified, and polite. That is using the OpenStreetMap API, all four of its meanings finally separated.
Reading What Comes Back: The Shape of a Response
Knowing what a response contains turns the three requests from incantations into tools. The editing API's map call returns XML whose top level elements are the database's own anatomy: node elements with lat and lon attributes and tag children, way elements listing node references in order, relation elements listing members with roles. Nominatim returns a list of candidate places, each with lat and lon as strings, a display name, a type, and an importance ranking that decides which "Springfield" you probably meant; when it returns several, your code, not the service, owns the disambiguation. Overpass returns an elements list in the same spirit as the map call, nodes with coordinates and tags, which your program then counts, maps, or stores. In all three, coordinates arrive as the raw material our Cartesian coordinates guide contrasts with grid systems: angles, ready for your code to project, measure, or display. Distances computed from them need proper geographic math, never flat subtraction, for the same reason a degree of longitude shrinks toward the poles.
From Requests to a Habit: Cache, Batch, and Be Boring
The difference between a script that runs once and a tool that runs daily is mostly manners, systematized. Cache geocodes permanently: an address's coordinates do not change, so a small local file or database table that remembers past Nominatim answers removes most of your request volume and all of your repeat latency. Batch with Overpass instead of looping: one query asking for every cafe in a town replaces five hundred geocoding calls, and the service would rather answer one heavy question than a hail of small ones. Back off on errors exponentially: a 429 answered with a pause of seconds, then tens of seconds, keeps you a citizen; a tight retry loop makes you an incident. Log what you fetched and when: open data changes, and a result you cannot date is a result you cannot defend, the same provenance discipline the GIS projects guide demands of finished maps. None of this is glamorous, and all of it is the actual craft of using a community API well. The services are generous; the habit that keeps them generous is being, in the best sense, a boring client: identified, patient, cached, and quiet.
Related Guides
If this page answered part of the question, these GIS and open map data guides cover the rest of the same ground:
- How to Use OpenStreetMap in Flutter: flutter_map, Tiles, Markers, and Search: Flutter has no official Google style map from the OpenStreetMap world, but the community package flutter_map gives you a full OSM map widget in...
- OpenStreetMap Attribution: How to Credit OSM Correctly on Any Medium: OpenStreetMap data is free to use, and the price is attribution: credit the OpenStreetMap contributors and link to the copyright page, in a place...
- OpenStreetMap Routing: OSRM, Valhalla, GraphHopper, and Which One to Call: OpenStreetMap itself does not route you anywhere; the routes come from a family of engines that read its data, each with a different design.
Frequently Asked Questions
Do I need an API key for OpenStreetMap?
No key for any read service: the editing API's reads, Nominatim, and Overpass are all keyless. What they require instead is good behavior: a real User-Agent identifying your app, rate limits respected, and caching. Writing to the database is the exception, needing an account and OAuth 2.0 authentication.
What is the difference between Nominatim and Overpass?
Nominatim geocodes: it converts place names and addresses into coordinates, and coordinates back into addresses. Overpass queries the database itself: it finds features matching conditions, like all cafes within 500 meters of a point, and returns the features. Names to coordinates is Nominatim; questions about the data are Overpass.
What is the Nominatim rate limit?
One request per second, and no bulk geocoding or per-keystroke autocomplete. You must also send a valid User-Agent identifying your application; default library user agents are refused. For heavy geocoding workloads, the policy's own advice is to run your own Nominatim instance on downloaded data.
Why did my map call return nothing or an error?
The two usual causes are the bbox order and the box size. The order is left (minimum longitude), bottom (minimum latitude), right (maximum longitude), top (maximum latitude): longitude first, which trips everyone once. And the box must be small, at most 0.25 square degrees, because the endpoint serves editors loading a neighborhood, not bulk extraction.
Can I use OpenStreetMap tiles in my app by downloading them?
Not in bulk. The tile servers are funded for browsing, and their policy forbids bulk downloading and scraping; heavy users get blocked. Use a tile provider, several offer free tiers, or download the underlying data as a planet file or regional extract and render your own tiles. Attribution to OpenStreetMap contributors is required either way.
What language do Overpass queries use?
Overpass QL, a compact query language of its own. The pattern in this article covers most beginner needs: set the output format and a timeout, select features by tag inside an area or radius, then output them. The around filter with a point and a radius in meters is the single most useful construction to learn first.
Photo credits: Daniil Komov (Pexels); Daniil Komov (Pexels). Photos are served from this site; follow the credit to the library page for the original.