|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:
While you have an internet connection...
While you're offline without an internet connection...
When you're back to an internet connection...
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
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.
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.
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:
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:
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.
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.
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.
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
Add new members to a relation
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.
This plugin helps ease the work with relations. Highly recommended when working with multipolygons.
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 josm.openstreetmap.de/wiki
Reverting entire changesets
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.
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 …' () 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 (