Overpass API/Sparse Editing

Overpass API · Language reference · Language guide · Technical terms · Areas · Query examples · Sparse Editing · Permanent ID · FAQ · more · Web site
Servers status · Versions · Development · Technical design · Installation · XAPI compatibility layer · Public transport sketch lines · Applications · Source code and issues

Overpass turbo · Wizard · Overpass turbo shortcuts · MapCSS stylesheets · Export to GeoJSON · more · Development · Source code and issues · Web site

Overpass Ultra · Examples · Overpass Ultra extensions · MapLibre stylesheets · URL Params · more · Source code and issues · Web site

If OSM data is highly dense in a certain area, or if you wish to visualize only certain objects in a wider area, it can help to combine the power of JOSM with Download from Overpass API downloads to selectively download objects meeting a certain criteria, then perform edits on them. Working in this way comes close to the concept of "layers" in classical GIS systems.

There are many advantages to sparse editing, especially including a reduced JOSM memory footprint while editing. This being said:

• sparse editing requires more care than usual while editing (because of parent objects/object dependencies)
• certain types of sparse editing may cross over into automated edits, requiring you to be aware of the automated edits code of conduct.

This article will start by discussing how sparse editing works and what to watch out for, then follow with a practical example.

Object dependency concepts

As you are probably already aware if you are reading this article, objects in OpenStreetMap can be nodes, ways, and relations. If you use Download from Overpass API to download only "some" objects in an area, the possibility exists that you will inadvertently exclude objects from the download that refer to objects you're about to edit. This can cause problems later when it's time to upload your work; it's a problem which in typical JOSM use you generally only see while editing at the brim/edge of the bounding box. First, a summary of how objects relate to one another.

• Nodes
  • May have one or more ways as parents
  • May have one or more relations as parents
• Ways
  • May have one or more relations as parents
  • Must have two or more nodes as children
• Relations
  • May have one or more relations as parents (super-relations)
  • Must have one or more nodes, ways, or relations as children

An Overpass API download will automatically download a way's child nodes, and/or a relation's child objects when they are downloaded. What this download does not do is automatically download the shared parents of those child nodes and objects.

In JOSM sparse editing, it is generally wise to check objects you will be directly editing for parents before you begin. It is possible to do this by highlighting the objects of interest, then use the Download parent ways/relations menu option in JOSM, (which can also be accessed with the key press Ctrl+Alt+D ).

Node conflicts

Changing the position of or deleting a node may affect an object you haven't downloaded which happens to share that node. The best practice is not to change the positions of, or delete nodes at all, when doing JOSM sparse editing. If you do and a change you make affects an object already saved on the server, you will encounter an editing conflict with nodes. In this situation, the safe thing to do is either to...

1. Not upload the changeset at all or
2. Resolve all node conflicts by using the version saved on the server. (You can do this with nodes one at a time in the "Conflicts" window with the "Resolve" button, by selecting a server's version of a node; or you can multi-select node conflicts in the "Conflicts" window, and using the context menu (right click), "Resolve to their versions".) If you resolve node conflicts in this manner, you will want to verify your changes after resolution, to ensure that yours are still properly completed at upload time.

Way conflicts

Splitting ways and merging ways can affect relations you haven't downloaded which happen to share that way as one of its members. The best practice is not to split or merge ways when doing JOSM sparse editing. If you do make a change like this and it affects an object already saved on the server, you will encounter an editing conflict with ways. In this situation, the safe thing to do is either to...

1. Not upload the changeset at all or
2. Resolve all way conflicts by using the version saved on the server. (You can do this with ways one at a time in the "Conflicts" window with the "Resolve" button, by selecting a server's version of a node; or you can multi-select way conflicts in the "Conflicts" window, and using the context menu (right click), "Resolve to their versions".) If you resolve way conflicts in this manner, you will want to verify your changes after resolution, to ensure that yours are still properly completed at upload time.

Also note: changing the position of nodes, adding nodes to a way, or deleting nodes from a way may change the geometry of an object you haven't downloaded. Use caution when changing a way's geometry if you suspect it is shared by multiple relations, such as multipolygons, borders, or bus/cycle/pedestrian routes. These changes won't necessarily cause a JOSM edit conflict, but can still make unintended geometry changes to objects you aren't aware of. (In JOSM, you can select the objects you intent to merge or split, and then press Ctrl+Alt+D to load all dependant ways or relations referencing the selected objects, before merging/splitting them, this will avoid edit conflicts most of the time when uploading your changes).

Example

As an example, we want to check which shops in Bonn already have a "wheelmap" tag and add it if applicable.

For this purpose we set the standard OSM map in black/white as a wallpaper in JOSM. Then we download the filtered data.

Install the background wallpaper

Select "Edit > Preferences ...".

Select "TMS/WMS", the lowest entry in the panel on the left.

Select from "Available default entries" the entry "OpenStreetMap (Mapnik Black & White)" and click "Activate", then "OK".

Select then "Imagery > OpenStreetMap (Mapnik Black & White)". You see a lighter grey. The real map will appear after we have chosen a bounding box in the next step. You can ignore the warning about misalignment because the OSM base map is by design the same way aligned as the data it is made from.

Download data

Select "File > Download data > Download from Overpass API".

Choose you desired bounding box from the "Slippy Map". You can zoom out and in with the mouse wheel. You can pan around by keeping the right mouse button pressed and dragging. You can choose a bounding box by dragging with pressed left mouse button.

Paste the following query to "Overpass query". We use here:

[out:xml][timeout:25][bbox:{{bbox}}];
( node[shop];
  way[shop];>;
  rel[shop];>;);
(._;rel(bn););
(._;rel(bw););
(._;rel(br););
out meta;

The syntax is explained in the next section below. The bounding box will be set by JOSM by including the [bbox:{{bbox}}] predicate. The crucial thing is that we download here also relations and refer to the downloaded objects such that JOSM can take care of them when we edit.

Click "Download" and wait until the download has completed. During the tests this has taken 5 to 15 seconds.

Please keep the precautions in mind. Or use it as a flexible read-only view for OSM objects of chosen category.

More useful queries

The entire street grid:

( way[highway];>;);
(._;rel(bn););
(._;rel(bw););
(._;rel(br););
out meta;

All public transport related data:

( way[highway];>;
  way[railway];>;
  node[public_transport];
  node[highway=bus_stop];);
(._;rel(bn););
(._;rel(bw););
(._;rel(br););
out meta;