The OSM Editing API & Changeset Upload

Reading OpenStreetMap is a technical decision. Writing to it is a social one, executed with technical tools, and the tools are deliberately shaped by the social expectations. The editing API will accept an authenticated changeset from any account within seconds of you writing your first script; whether that changeset stays in the map depends entirely on choices that have nothing to do with HTTP.

The changeset lifecycle from open to close Four stages. Opening a changeset submits metadata including a comment, a source and the creating software, and receives a changeset identifier. Reading fetches the current version of every object the edit will touch, which is the only defence against overwriting somebody else's work. Uploading submits an osmChange document containing creates, modifications and deletions, which the server applies atomically or rejects entirely. Closing finalises the changeset so it becomes visible for review and revert. Four calls, and the second one is not optional open comment, source, tool returns an id read current version per object the conflict defence upload osmChange document atomic: all or none close finalise the changeset reviewable, revertible Skipping the second call is how an automated edit silently reverts a mapper's correction made twenty minutes earlier.
The upload is atomic, which means a single stale version rejects the entire document — that is a feature, not an obstacle.

The Problem This Topic Solves

Sometimes the right outcome of a data pipeline is an improvement to OpenStreetMap itself: a systematic tagging error you have detected across a region, an authoritative dataset that genuinely adds information the map lacks, a set of objects whose geometry you can demonstrably improve. The editing API is how that gets back.

The failure scenario is well documented in the community’s collective memory. A team runs a bulk edit without discussion, using a script that reads objects once, holds them for an hour, and uploads with versions that have since moved on. Some uploads conflict and are rejected; the script bumps the version numbers to force them through; the edits silently overwrite corrections made by local mappers in the meantime. The changeset comment says “data import”. Nobody can tell what the source was or whom to ask. The result is a revert, a mailing list thread, and a team that is now unwelcome. Every step of that is preventable by the practices below, and none of them is technically difficult.

Prerequisites

Understand the element model in Node, Way & Relation Data Model, because an edit that touches a way’s node list is a very different proposition from one that only touches tags. Read the parent Querying OSM: Overpass, Nominatim & APIs overview for the service’s role. And be clear on identity and versioning, covered in OSM Feature Identity & ID Stability — the version number is the whole basis of the API’s concurrency control.

The Changeset as the Unit of Everything

A changeset is not a transaction wrapper; it is the unit of review and the unit of revert. That single fact determines how you should size and scope one.

A changeset containing five thousand objects spanning four unrelated fixes cannot be reverted selectively: undoing the one mistake undoes the four good changes with it. A changeset containing one coherent fix across a bounded area can be reviewed in a minute and reverted cleanly if it turns out to be wrong. The engineering rule that follows is: group by what a revert should undo, not by what is convenient to batch.

The metadata carries equal weight. Three tags should be present on every automated changeset:

  • comment — what changed and why, in a sentence a stranger can evaluate.
  • source — where the data came from, specifically enough to check.
  • created_by — the tool and version, so a systematic error can be traced to its cause.

A contact point, whether in the comment or as a link to a documented wiki page describing the edit, is what turns “suspicious automated edit” into “let me ask them about this”.

How changeset size affects review, revert and trust Three panels covering changeset sizing. A small single-purpose changeset covering one fix in a bounded area can be reviewed in minutes and reverted cleanly, and it builds trust because each one is evaluable. A large single-purpose changeset is still revertible as a unit but is hard to review and its blast radius is wide. A large mixed changeset combining unrelated fixes cannot be reverted selectively, so undoing one mistake destroys the good changes with it, and it is the shape most likely to be reverted wholesale. Size the changeset by what a revert should undo Small, single purpose One fix, bounded area Reviewable in minutes Reverts cleanly on its own Each one builds trust The shape to aim for Large, single purpose One fix, wide area Hard to review in full Still reverts as a unit Wide blast radius Split by area if you can Large, mixed purpose Several unrelated fixes Effectively unreviewable Cannot revert selectively One error loses all of it The shape to never ship A reviewer who cannot tell what a changeset was for has only one safe option available to them, and it is the revert button.
Batching unrelated fixes together is convenient for the uploader and hostile to everybody who has to evaluate the result.

Optimistic Locking and the Version Field

Every OSM object carries a version number that increments on each edit. When you upload a change, you state the version you believe you are modifying. If the server’s current version differs, it rejects the entire changeset with a conflict response naming the offending object.

This is optimistic locking, and it is the mechanism that stops concurrent editors from silently destroying each other’s work. Two consequences matter for a pipeline.

First, the read-to-write window must be short. Reading objects, computing changes for an hour, and then uploading maximises the chance that something moved. Read immediately before uploading, in the same run, ideally in the same few seconds.

Second, never resolve a conflict by bumping the version. The conflict means somebody edited the object after you read it. Incrementing the version number you send does not merge their change; it overwrites it. The correct response is to re-read the object, re-evaluate whether your edit still applies to the new state, and either re-apply it or skip the object — a distinction developed in Uploading an OSM Changeset from Python.

The osmChange Document

Uploads are submitted as an osmChange XML document with three sections — create, modify and delete — applied in that order. Several details routinely surprise people.

New objects use negative ids. An object being created is given a negative placeholder id, and the server returns a mapping from your placeholder to the real assigned id. Ways referencing newly created nodes reference the negative ids, and the server resolves them.

Modification is a full replacement. There is no partial update: a modify element carries the object’s complete tag set and, for a way, its complete node list. Sending a modify with only the tag you changed deletes every other tag on the object. This is the single most destructive mistake available through this API.

Deletion has ordering constraints. A node that is a member of a way cannot be deleted while the way references it. The delete section is applied last precisely so that a way can be deleted in the same changeset as its nodes.

Validation and Error Handling

Condition Root cause Detection Remediation
HTTP 409 conflict Object version moved since you read it Response names the object and both versions Re-read, re-evaluate, re-apply or skip — never bump
HTTP 400 with a precondition failure Referenced object missing or already deleted Response names the missing reference Re-read the referencing object; it may already be fixed
Tags disappeared after an edit modify sent a partial tag set Object has only the tags you sent Always send the complete current tag set plus changes
Way geometry destroyed modify sent a partial node list Way has only the nodes you listed Send the complete node list on every way modification
Changeset rejected as too large Element count above the server limit Explicit size error on upload Split into several smaller, single-purpose changesets
Upload succeeds, edit is reverted No discussion, no source, no contact A revert changeset referencing yours Document the edit and discuss before repeating it
HTTP 429 on upload Write rate limit exceeded Rate-limit response Slow down; write volume is deliberately constrained

Performance, Scale and Restraint

Everything about this API’s performance profile is a deliberate signal. Writes are rate limited. Changesets have element ceilings. Bulk reads are discouraged in favour of extracts and Overpass. These are not obstacles to engineer around; they are the system telling you that its write path is designed for human-scale editing and for automation that behaves like a careful human.

The practical scaling pattern for a large systematic edit is therefore not “upload faster” but “upload in reviewable pieces over time”: split by area, cap each changeset at a few hundred objects, pause between them, and watch for feedback. That cadence gives local mappers a chance to notice and object before the whole edit has landed, which is precisely the point.

The sequence a large automated edit should follow before any upload happens Four stages spread over time. The proposal stage documents the edit on a wiki page and raises it on the relevant community channels, before any code is written. The dry run stage executes the entire edit against the development API to prove the mechanics work without touching live data. The pilot stage uploads one small bounded area to the live map and waits for feedback. The rollout stage proceeds area by area with pauses, so objections can still change the outcome partway through. Four stages, and three of them happen before the live map propose document and discuss before writing code dry run against the dev API proves the mechanics pilot one small area, live then wait for feedback roll out area by area, paused objections still count The pilot means a mistake costs one small area rather than a country, and objections arrive while they can still change the plan.
Each stage exists to make the next one cheaper to reverse, which is the only reliable protection against a systematic error.

Failure Modes and Gotchas

  • Partial modification deletes data. A modify replaces the object wholesale. Read the current object, apply your change to that complete state, and send the result.
  • Version bumping overwrites people. A conflict is information about a concurrent edit, not an obstacle. Re-read and re-evaluate.
  • Negative ids are per-changeset. Placeholder ids have no meaning outside the document that declares them; do not persist them.
  • An unclosed changeset stays open. It will eventually time out, but until then it is visible and confusing. Close in a finally block.
  • Deleting a referenced node fails. Delete the referencing way in the same changeset, or leave the node alone.
  • The development API is a separate world. Different accounts, different data, different object ids. Code that hard-codes ids will not move between them, which is exactly why a dry run should exercise the full pipeline rather than a fixture.
  • Rate limits apply to writes specifically. A read-heavy client that also writes can be throttled on the write path while reads continue fine, which makes the symptom confusing.

Integration Points

Upstream, the decision about what to edit should come from a validation process, not from an ad hoc query — the rule catalogue in Authoring OSM Validation Rules is the right source of candidate fixes, because a rule that has been reviewed and measured for false positives is a far better basis for a bulk edit than a hunch. Where the edit originates in an external dataset, the matching and scoring belongs in OSM Conflation & Data Enrichment and the audit in Auditing a Conflation Run Before Upload.

Downstream, your own copy of the data is now behind the map you just changed. If you run a replication pipeline, your edits will come back to you through the diff stream like anybody else’s, which is a useful end-to-end check that they landed as intended.

Guides in This Topic

Frequently Asked Questions

Why did my changeset delete tags I never touched?

Because a modify operation replaces the object completely rather than patching it. If the document you uploaded listed only the tag you changed, the server took that as the object’s full tag set and removed everything else. The fix is structural: always read the object’s current state immediately before uploading, apply your change to that complete state, and send the whole result. The same applies to a way’s node list.

What should I do when the API returns a version conflict?

Re-read the object and decide again. A conflict means somebody edited it after you read it, so your change was computed against a state that no longer exists. Sometimes their edit already fixed what you were fixing; sometimes yours still applies cleanly; sometimes the two genuinely conflict and the object should be skipped and reviewed by a human. Incrementing the version number to force the upload through discards their work silently and is the behaviour most likely to get an account blocked.

How large should an automated changeset be?

Small enough that a reviewer can understand it and that a revert undoes exactly one thing. A few hundred objects covering one coherent fix in a bounded area is a good target. The technical ceiling is much higher, but changesets are the unit of review and revert, so a large mixed changeset forces a reviewer who spots one problem to choose between accepting it and destroying everything else in the same upload.

Do I have to discuss an automated edit before making it?

For anything systematic or bulk, yes — that is the community’s documented expectation, and it is also straightforwardly in your interest. A discussion surfaces regional tagging conventions you did not know about, finds the local mappers who will review your work, and produces the wiki page you can link from every changeset comment. Edits that arrive without any of that get reverted on suspicion, regardless of whether they were technically correct.

Can I use the editing API to read data in bulk?

No — and not because it will refuse, but because it is the same machinery every editor depends on and it is not built for that load. Reading single objects to check their current version before an edit is exactly what it is for. Reading a region, a category of features, or anything you would describe as a dataset belongs to Overpass or, better, to a downloaded extract.

Up one level: Querying OSM: Overpass, Nominatim & APIs.