JOSM/Advanced editing

From OpenStreetMap Wiki
Jump to navigation Jump to search
Start and download OSM data Basic editing Advanced editing Plugins FAQ

Saving and loading .osm files

For most purposes you'll probably want to stick with downloading data and uploading your changes. When you upload your changes you have effectively "saved" your changes. Better than that, you've made your changes available for other people to see on the map, and to make further changes to. OpenStreetMap is all about internet collaboration! However JOSM can also work with files on your local filesystem, saving and opening files to/from your local disk. This works much like any other normal desktop application.

Use 'file' menu > 'Save As...' to save data (and your changes) to a file.

Use 'file' menu > 'Open...' to open a previously saved file for editing or uploading.

The JOSM file format is an XML representation OpenStreetMap data in the standard .osm format. JOSM extends this slightly to store details of changes to OpenStreetMap data, that is, any changes which were not uploaded already at the time when the file was saved. This is a powerful feature which means JOSM can be used as an offline editor as follows:

Offline editing

While you have an internet connection...

  • Download an area of the map (can be one or several bounding boxes)
  • Save the data as a .osm file on your local disk.

While you're offline without an internet connection...

  • Open the file
  • Maybe open GPS traces and overlay them on the data (This can also work fine offline)
  • Make changes e.g. add local information you have captured while out surveying
  • Save changes back to file. The file includes information about all your changes including moving and deleting data.

When you're back to an internet connection...

  • Open the file from your disk into JOSM
  • Do "File" menu > "Update Data" to re-download the areas you worked on. Resolve any conflicts (see following section)
  • Click upload to save the changes to the OpenStreetMap server.

Filtered Data

You can filter OpenStreetMap data (e.g. by tags, to give a thematic extract) either by manipulating .osm files on your disk using tools such as osmosis, osmconvert or osmfilter, or by requesting filtered data from a specialised API such as XAPI or Overpass API. You then can load filtered data into JOSM. This can be the best way to get a look at it, but take care when editing. You should not delete or move any nodes without first doing a normal unfiltered download around it, to get all connected elements.

Geometry and topology edits

Adding and adjusting nodes of a way

You can move nodes and ways by selecting them and, while still in (S)elect mode, dragging them. The vast majority of the time you will be interested in moving only one node at a time. Clear your selection before dragging the node. If you accidentally move a whole way use Ctrl-Z to undo.

You can add nodes to the middle of a way by going into (A)dd mode, and clicking on a way segment at the desired place. Return to (S)elect mode afterwards, unless you are building a connecting way. To add another node along this way segment, be sure to clear your selection before adding again. Take care when adding nodes in a situation where lots of ways are nearby (criss-crossing or running in parallel) It's quite easy to accidentally add a new node which bunches together several ways. Undo! The easiest way to avoid this, is to temporarily zoom right in, so that things are spaced out nicely.

There is another trick for adding nodes to an existing way. Look out for the little crosses appearing midway along the segments. You can drag these to quickly add a node without leaving select mode.

Delete a node by selecting it, and pressing Delete key. This will delete the selected objects, but keep you in (S)elect mode.

Splitting and combining ways

JOSM-Icon-splitway.svg You can split one long way into two smaller ways. Select the node where the split should occur, and select 'Tools' menu > 'Split Way'. You can do this several times to chop a way in several places. The resulting ways will share the same tags initially, but they are separate ways now. You can give them different tags.

Sometimes you need to do some clever selecting to indicate exactly which split JOSM should perform. If a node is connected to multiple ways, you must select the node and the way that you wish to split. To do this, select the way and then while holding shift, click on the node . Another trick is to select two nodes before clicking 'Split Way'. By doing this, a way can be split at the two different nodes at the same time. This can be a time-saver, but you are actually required to do this when splitting a way which is forming a loop.

JOSM-Icon-combineway.svg The opposite kind of operation, is to combine two ways together to form one. You can only do this with two ways which are arranged end-to-end (they are lined up ready to be combined into one way) Select both of the ways at the same time. Again this can be achieved by holding down shift to add to your selection. Click 'Tools' menu > 'Combine Way'. At this point JOSM will create a single way. If the two ways had different tags, then the combined way will share all tags of both. You may be prompted to "solve conflicts" with tags, where the same key is set to different values on the two different ways. Remember tags always apply along the entire length of a way. If you need different tags, you need different ways.

JOSM-Icon-wayflip.svg The reverse way action will change the direction of the way. Every way has a direction which is indicated with arrows when the way is selected. As mentioned above, ways must be arranged end-to-end before they can be combined, and this includes pointing in the same direction (although it will prompt you to automatically do a reverse if they are not correctly end-to-end). Often the direction of a way doesn't matter, but it can be used to indicate directional features. Some important examples include:

  • Oneway restrictions with the oneway=yes tag.
  • waterway=river should be pointing the direction of flow (downhill)
  • natural=coastline which must have a direction with land on the left, sea on the right.

You can adjust the topological layout of nodes and ways with many alternative sequences of clicks and keypresses. This can be confusing at first, but you'll master it with a bit of practice. Use Ctrl-Z to undo. Have a play!

Unglueing and untangling

In the JOSM/Basic editing section we described how to edit nodes and ways, and also operations such as split/combine/and reverse ways. Things can get a little more tricky when data is intertwined, overlapped or tangled in a complex manner, but remember you can always try to make changes and then 'undo' a few steps if things don't work out. You can also temporarily move nodes or even delete elements to understand linkages and overlaps, before undoing to restore the data. Here are a few additional editing techniques:

Overlapping ways, where two or more ways are drawn exactly on top of each other between the same two nodes, this can happen by accident or may be a correct representation of something (Two highways should not normally overlap each other like this, but you may come across landuse areas with nodes shared with the bordering highways for example) In this situation you may need to select one or the other of the overlapping ways. There are various ways of doing this:

  • A middle-click reveals a context menu showing the different tags of all the elements under the mouse.
  • Holding down Ctrl will allow you to click the menu to change the selection.
  • Alternatively repeated middle clicking will cycle through the selection.
  • If you do not have a middle mouse button, hold down the 'Alt' key on the right side of your keyboard and do a repeated left-click to cycle through the selection

Unglue ways is an option on the 'Tools' menu. If two (or more) ways are connected at one node, this option will create a second node, freeing one way from the other. Note that this normally results in a 'duplicate node' (two different nodes sitting exactly on top of one another) with both nodes being selected. As a follow-up, or just to understand the situation, you may want to clear your selection and then drag just the top node off to one side. You should do this to avoid leaving a duplicate node in the data. They are usually regarded as a bad thing, often resulting in confusion and routing connectivity problems. There should be no need for them in the data. The 'unglue ways' action can also be used with a way element selected, to unglue it from any nodes it shares along it's entire length. If you want to merge such nodes together again, use 'Tools' > 'Merge nodes' - but note that this merges all nodes that are very near.

The features described here are particularly useful for working with complex data. There are several other actions on the tools menu, and more can be installed via plugins.

Resolving conflicts

While you are editing with JOSM, there's a chance other people could be editing the same area of data at the same time. JOSM only downloads data when you ask it to, which means you can have quite long editing sessions without necessarily noticing potential clashes with other contributors.

In general it is a good idea to upload regularly if you are able to do so, to reduce the chance and also the impact of any conflicts. But it can also be a good idea to download prior to uploading. The download action does not overwrite your changes with data from the server. There is no need to worry about losing any of your changes, but it does open up the possibility to see changes other users may have made (or new data they have added) before you do your upload.

Clearly these changes made by other users are something you should check prior to uploading. If another user has changed exactly the same element which you have also changed, then JOSM reports a "conflict". At this stage you have not yet uploaded your changes. You are forced to resolve conflicts before you upload. This feature is designed to help you find areas where you have clashed with other users. It allows you to pick and choose whether to overwrite other people's changes with your own in each case. Once you have resolved the conflicts you can upload your changes.

JOSM-Icon-conflict.svg Toggle visibility of the conflict panel on the right. Here the conflicts are listed, and you can open a window to resolve each one. You are given the choice of which version to keep, yours or theirs. Various tabs and displays are designed to help you understand what the data represents in each case. This can seem a little complex and unclear, but it always comes down to the simple choice: keep yours or theirs. "Theirs" refers to the current state of the data on the server, which is a change from the state of the element as it was when you originally downloaded it, i.e. it appears that somebody else has edited this element.


Relations are a type of element which can be used to represent some more advanced kinds of map features and geodata, such as routes and turn restrictions. Elements like "nodes" and "ways" can be members of relations. Relations can be members of relations too (a hierarchy). For each of these memberships the "role" can be named, and the overall relation is given tags. See the Relations page for more details.

JOSM provides an interface to give you raw editing power over relations. There are several ways of accessing the main relations dialog.

JOSM-Icon-relationlist.svg The relations panel can be shown on the right-hand side. Toggle visibility by clicking the button on the left. The panel lists all relations in the downloaded area, and provides buttons to create, edit, duplicate, delete, and select a relation.

The "Tags/Memberships" panel, which you normally use to view and edit tags, will also show relations, this time just those of the selected element (the element's memberships).

For creating brand new relations you need to use the relations panel, but both the panels give access to the dialog for editing existing relations. The main relation editing dialogue is split into three areas. At the top you can edit the tags of the relation. At the bottom-left is list of elements which are members, with a column for the roles. The list is ordered (which may or may not be significant). On the bottom-right there is a pick-list of elements. This list is linked to the element selection you currently have in the background data view. Adjust your selection in the background to bring elements onto the list which can then be added to the relation.

Create a new relation

  • In the Relations panel click on the "Create a new relation" button
  • In the "Create new relation" window add the appropriate tags
  • Add relation members and add appropriate roles
  • Click OK to close the "Create new relation" window
  • Video example

Add new members to a relation

  • In the main window select the ways/nodes to be added to the relation
  • Select the required relation from the list of relations in the Relations panel
  • Click on the "Open an editor for the selected relation" button
  • In the "Edit relation" window select the existing member (if present) that the new node/way is next to and click on the appropriate "Add all primitives..." button in the Selection area
  • Click OK to close the "Edit relation" window

JOSM allows you to sort members, and this is recommended for some types of relations. e.g. route relations, multipolygons, .... Sorting the members allows you to ensure the members are connected, and to locate any unconnected ways. To sort the members click the A-Z button in the relation editor.

Relations Toolbox

This plugin helps ease the work with relations. Highly recommended when working with multipolygons.

More information

Tagging Presets

JOSM supports tagging presets distributed as XML files that describe the GUI for entering tags (or properties, annotations, sometimes called map features), available when using the Presets menu in JOSM. The XML files can be placed anywhere in the web or at the users local file system.

Presets can be added by the users in JOSM's Preferences under Map Settings on the Tagging Presets tab. After they have been added, the presets (menus or single buttons) can be added to the toolbar in JOSM's Preferences under Toolbar customization.

More information at

Reverting entire changesets

See JOSM reverter plugin

Reverting individual objects

Suppose you have modified (or deleted) an object and realize later that you don't want to upload that modification. "Undoing" all the way back to before you modified the object would lose all the other changes you made since then, or you may have already lost the undo stack if you restarted JOSM and reloaded a session. One possible solution is to "Upload selection" and ensure the object is not selected, but in general, "Upload selection" doesn't give you a good way to visualize and review what the state of the entire map will be after your upload. So it's often best if you can revert your local modification to the individual object and then do a normal "Upload data".

Here are the best techniques that I (m3232 a.k.a. Matt McCutchen) could find to do this in various cases as of JOSM revision 18191. (I may be wrong about some things. Others feel free to improve this write-up!) These techniques can also be used to revert objects to versions other than the latest (which, of course, will leave them "modified" with respect to the latest version) and may be preferable in some situations to reverting individual objects via the "reverter" plugin. Below, "open the desired version in the history" means: select the object, click "History" in the Selection window, and choose the version you want to revert to in column A.

  • Tags of any object: Open the desired version in the history, select the tag(s) to restore, right-click, and "Restore selected tags".
  • Coordinates of a node: Open the desired version in the history, go to the Coordinates tab, right-click anywhere in the map view on that tab, and "Restore".
  • List of nodes in a way: I didn't find a way to edit it directly, but once you open the old node list you want to revert to in the history window, you can typically get there with the "Join Node to Way" and "Disconnect Node from Way" commands. If "Join Node to Way" does not work because the node is too far from the correct part of the way, first move the node to a suitable place, perform the "Join Node to Way", and then restore the node's coordinates.
  • List of members of a relation: Open the old member list you want to achieve in the history window and then directly edit the member list in your local data layer. If you know the ID of an object you want to add and need to select the object in order to use the button to add it to the relation, you can perform a search such as "type:node id:12345678".
  • Undeleting any object: If the object is deleted in the latest uploaded version, try the "Undelete object" command provided by the "undelete" plugin. If it is not deleted in the latest uploaded version and is deleted only in your local copy, you should be able to just "Purge" and re-download it because any dependent objects would already have to be deleted from your local data layer.
  • Reverting creation of an object: Just delete it.
  • At any time, to find all objects that would be uploaded if you "Upload data", you can search for "modified OR deleted" with the "all objects" box checked (important!); you may wish to add a toolbar button for this search. If an object still shows as modified even though it has no actual diff from the latest uploaded version, you can use "Update selection" or "Update modified" to clear the object's modified state. Note that JOSM may sometimes consider a way to be modified if any node on it has changed coordinates, even if there is no change to any of the data that is actually part of the way in the osm file (i.e., the tags and the node list). However, if you revert the node coordinates, then a subsequent "Update selection" or "Update modified" command should clear the modified state of the way.
  • If all else fails, you can manually edit the osm file in a text editor, but avoid this because it is very easy to make mistakes.

Load a local GPX file

Above we described using the download dialog 'slippy map' tab to choose an area to download when we first start JOSM. Another approach is to load in a GPX file before downloading data. If you want to do some editing without using GPS traces, skip this section. Here we will assume you have figured out how to get data off your GPS device and into a GPX file (or NMEA file) on your local disk (See Making GPX Tracks)

Opening your GPX file is very straightforward. Click 'File' menu → 'Open …' (JOSM-Icon-open.svg) and choose the file.

When JOSM is displaying a GPS trace, you can zoom and pan using the scrollwheel and right mouse button as described above.

Now you can follow exactly the same procedure to download some map data alongside your GPS trace. As described in the previous section, position the visible area of the screen, and click the download button to get some data. As always, you should take care to avoid downloading too much data. If your GPS trace is from a short walk, then you might typically download an area encompassing the whole thing, but if it is a longer trace, travelling through a dense complex area of the map (e.g. a car journey driving through a city) then this might be too much data. Instead you should zoom in on just one end of your trace and grab a small rectangular area to start with.

Download other people's traces

OpenStreetMap has a database which is separate from the main map data, especially for sharing raw GPS data. You can download any raw GPS data which others or you have contributed in the area you are looking at. This is an additional tickbox option in the 'Download' dialog.

Working with other people's traces is not required and often may not be very useful, but it can give a useful indication of how accurate your own trace is, and how existing data has been positioned. Where several traces have been taken along the same road, it may be useful to judge the position of an average line, to reduce the inaccuracies of GPS. As well as viewing other people's traces, you can upload your own. Again this is not required.

Add custom imagery

Sometimes you will find a governmental source, licensed as open data, that is not yet among the list of JOSM imagery sources. Sometimes you need to enter an URL in an editor that supports JOSM-compatible syntax for the URL placeholders. In these cases, you can follow the JOSM specification that defines the placeholders allowed in the imagery URLs, for each URL type (tms:..., etc).

Next >>