Say "the OpenStreetMap API" to a room of developers and half of them picture a data firehose: an endpoint you call to fetch the map for your app. That picture is wrong, and building on it wastes weeks. The OpenStreetMap API is the project's editing interface, the same door the iD editor and JOSM walk through when a mapper adds a road or moves a node. It reads small areas precisely and writes changes carefully, and it is deliberately capped so it cannot be used as a bulk download channel. Understanding that single fact reorganizes everything else: the version history, the limits, the authentication, and the family of sibling services that exist precisely to do the jobs this API declines. This guide draws that map, so you can stop asking the editing door to be a warehouse.
Home / GIS and Open Map Data for Beginners
The OpenStreetMap API: What It Is, What It Caps, and What It Is Not For

Photo: Nemuel Sereti / Pexels
Guest in the Commons: The OSM API Checklist
Check off each step as you finish it. Your progress stays on this page.
0 of 8 complete
0% done
What the API Is: The Editing Interface
The API's data model mirrors the map itself. The world is made of nodes, points with coordinates; ways, ordered lists of nodes forming lines and areas; and relations, groupings of nodes, ways, and other relations into routes, boundaries, and multipolygons. Everything carries tags, the key-value pairs that say what a thing is. The API exposes this model directly: you can fetch a node, a way, or a relation by ID; fetch the elements of a small area; and, as an authenticated editor, create, modify, and delete elements inside a changeset, the unit of work that groups one editing session's changes with a comment explaining them. The current version, 0.6, has been in service since April 2009, a longevity that tells you something true about the project: the editing interface is infrastructure, changed rarely and carefully, because every editor, validator, and history tool on earth is built against it. Around the core sit supporting calls an editor needs: user details and preferences, the notes system for reporting problems without editing, GPS trace upload and retrieval for the tracks mappers collect, and changeset queries and discussions that make the social layer of editing, review, comment, revert, possible. If your mental model is "the API is how the map gets written," every one of those pieces makes sense.
The Map Call and Its Caps
The API's most famous endpoint is the map call, which returns all the data in a bounding box: every node, way, and relation in a rectangle of the world, the call an editor makes when it opens an area to work on. Its caps are the clearest statement of the API's purpose. The box is limited to about a quarter of a square degree, and the response is limited to 50,000 nodes; ask for a whole city at full detail and the call refuses, by design. The usage policy around the API adds the operational corollaries: clients should keep simultaneous download connections to a maximum of two, and systematic scraping of the API is prohibited outright. These are not the limits of a stingy service; they are the shape of an editing tool. An editor opening a neighborhood needs a neighborhood, complete and exact, and needs it fast. Nobody editing honestly needs a continent through the editing door, and the continent is available elsewhere, as planet files and extracts, through channels built for bulk. Developers who internalize this stop fighting the caps and start routing each job to the service built for it, which is the subject of the next section but one. Until then, hold the rule in its simplest form: if your request would embarrass an editor, the API is the wrong door.
Authentication: OAuth 2.0 and the End of Passwords
Reading public data through the API needs no account. Writing does, and how writing authenticates has modernized. The API historically accepted HTTP Basic authentication and OAuth 1.0a; both were shut down in June 2024, and edits today authenticate with OAuth 2.0, the same standard the rest of the web settled on. Practically, this means an editing application registers with OpenStreetMap, sends its user through an authorization flow, and receives tokens scoped to the permissions the user granted, reading private data, modifying the map, managing notes, and so on, which the application then presents with its calls. For developers this is unambiguously better: no application ever handles a user's password, permissions are granular and revocable, and a leaked token is a smaller fire than a leaked credential. For the ecosystem it closed a long tail of legacy clients, which is why older tutorials that walk through Basic auth or OAuth 1.0a now fail at the first write, a useful reminder to date-check any OpenStreetMap development guide you follow. The read side of your application may never need any of this; the moment your software writes to the map on someone's behalf, OAuth 2.0 is the only door, and building the flow early is cheaper than retrofitting it after launch.

Which Service Owns Which Job
Most OpenStreetMap integration mistakes are really routing mistakes between services, so here is the whole map in one place. To edit the data, or fetch a small area exactly as an editor would: this API. To query the data at scale, every restaurant in a county, all the cycleways in a country, filtered by any tag combination: the Overpass API, built for read-only questions over the full database. To turn words into coordinates and back: Nominatim, the geocoder. To compute a route: one of the routing engines, OSRM, Valhalla, GraphHopper, or OpenRouteService, compared in our guide to OpenStreetMap routing. To display a map: tile services or vector tile providers, governed by their own usage policies. To download a region whole: planet files and extracts from community mirrors, the bulk channel the API's caps keep pointing you toward. Each service carries its own limits and etiquette because each carries different costs, and the pattern that unifies them is the project's founding bargain: the data is free, the infrastructure is shared, and the price of both is using the right door and not leaning on it. Our guide to using OpenStreetMap data covers the licensing half of that bargain; this section is the engineering half.
Changesets: The Unit of Trustworthy Editing
If the API has a social heart, it is the changeset. Every write an editor makes happens inside one: the editor opens a changeset, uploads a set of creations, modifications, and deletions, and closes it, and the changeset carries a comment describing the change and tags recording the editor used and the sources consulted. This structure is why a crowdsourced map edited by millions does not dissolve into noise. Changesets make editing reviewable: any other mapper can open a changeset, see exactly what changed on a map, read the stated reason, and discuss it in the changeset's comment thread. They make editing revertible: a vandalized or mistaken changeset can be undone as a unit, restoring the prior state without hand-hunting every element. And they make editing accountable in the gentle, cumulative way that actually works: a mapper's history is their changesets, and the community's trust in a contributor is built from reading them. For a developer building on the API, the lesson is to treat changesets as the API's transaction and its audit log in one: open them deliberately, comment them honestly, keep them geographically and thematically coherent, and close them when the work is done rather than leaving them to time out. An application that writes to OpenStreetMap is joining a community's workplace, and the changeset is how it introduces itself, every single time.
A Developer's First Hour With the API
The productive way to meet this API is with small, real experiments against its read side. Fetch a single node by ID and read its tags until the data model stops being abstract. Fetch a way and notice it is a list of node references, then fetch one of those nodes and feel the graph assemble. Make a map call over the neighborhood you know best, a box small enough to respect the caps, and compare the returned data against the streets outside your window; you will learn more about what OpenStreetMap knows, and what it misses, in that one comparison than in a day of documentation. Read a few recent changesets in your area and their comments, to absorb what normal editing looks like before your software ever writes. Then, and only then, register an OAuth 2.0 application and make a tiny, careful edit through the development environment the project provides for exactly this purpose, so your first write harms nothing while it teaches everything. Developers who take this hour arrive at production integrations with the API's grain in their hands. Developers who skip it ship software that fights the caps, misunderstands the model, and treats the editing door as a warehouse, and the API, politely and automatically, declines to cooperate.
Rate Limits and the API's Social Contract
The read side of the API asks for restraint in specific, learnable forms. The map call's caps, the area ceiling and the element ceiling, are the famous ones, but the etiquette runs deeper: identify your application with an honest user agent rather than a generic library default, cache what you fetch rather than re-asking on every page view, and never build a service that polls the main API for freshness when the project's replication feeds exist to stream changes properly. These are not the rules of a company protecting a product. They are the house rules of a commons protecting its one shared server room, and they are enforced with a light touch precisely because most developers honor them on first hearing. The developer who internalizes the contract early builds differently: downloads become deliberate, caches become architecture, and the API's generosity, free reads of the entire living map, stops looking like a loophole and starts looking like what it is, an invitation with terms. Accept the terms and the API will carry production workloads for years. Treat it as an unlimited pipe and the pipe, politely, narrows.
Related Guides
Readers working through this topic usually need its closest companions too. These GIS and open map data guides cover the neighboring ground:
- OpenStreetMap Basemaps: One Dataset, Many Faces: Every OpenStreetMap basemap is a portrait of the same sitter.
- JOSM: The OpenStreetMap Desktop Editor for Mappers Who Outgrow iD: JOSM is the Java desktop editor that serious OpenStreetMap contributors graduate to: it edits relations comfortably, validates your work before...
- OpenStreetMap Tags Explained: How key=value Describes the Whole World: OpenStreetMap describes everything on earth, every road, river, cafe, and bench, with one tiny invention: the tag, a key and a value joined by an...
- OpenStreetMap Zoom Levels: What You Can See From Level 0 to 19: Every slippy map, OpenStreetMap included, is built on a ladder of zoom levels, 0 to 19 on the standard layer, where each step doubles the tiles in...
Frequently Asked Questions
What is the OpenStreetMap API used for?
It is the editing interface of OpenStreetMap: the API through which editors and editing software fetch small areas of the map and write changes back as nodes, ways, relations, and tags, grouped into changesets. It is not a bulk download or general application data service.
What are the limits of the API map call?
The map call returns data for a bounding box of at most about 0.25 square degrees, and responses are capped at 50,000 nodes. The usage policy also asks clients to keep to a maximum of two simultaneous download connections, and systematic scraping is prohibited.
How do applications authenticate to edit OpenStreetMap?
With OAuth 2.0. Basic authentication and OAuth 1.0a were shut down in June 2024. An application registers with OpenStreetMap, the user authorizes scoped permissions, and the application writes using the resulting tokens, never the user's password.
What API version does OpenStreetMap run?
Version 0.6, in service since April 2009. Its long stability is deliberate: the world's editors and history tools are built against it, so the project changes it rarely and carefully.
If not the API, how do I get OpenStreetMap data for my app?
Match the job to the service: Overpass API for filtered queries at scale, planet files and regional extracts for bulk downloads, Nominatim for geocoding, a routing engine for directions, and tile providers for display. The editing API is the one door not built for application data.
Photo credits: Nemuel Sereti (Pexels); Markus Spiske (Pexels). Photos are served from this site; follow the credit to the library page for the original.