JOSM/Basic editing

From OpenStreetMap Wiki
< JOSM(Redirected from JOSM/Upload changes)
Jump to navigation Jump to search
Start and download OSM data Basic editing Advanced editing Plugins FAQ

This page describes some basic ways of editing map data in JOSM.

Basic editing assumes you have downloaded data and you know how to zoom and pan around

Undo / Discard changes

JOSM generally doesn't read or write data to the OpenStreetMap database except when you ask it to, but at any time before uploading, you can discard all your changes by closing down JOSM (or by deleting the active data layer). You can also undo individual editing actions by clicking the undo toolbar button (JOSM-Icon-undo.svg) or by pressing Ctrl+Z. So relax! If you make a mess of your editing at any point, you can always undo a few steps.

If you upload erroneous changeset during your learning process, please contact other OSM members to assist you in questions and first edits not covered by this guide. But please be patient to study optional topics covered by this guide if you encounter problem, yes they are quite big, but you should find answer to your problem :-)

(S)elect and (A)dd

JOSM Keyboard Shortcuts Cheat Sheet A3 300 DPI Printable version

There are two main modes of operation when editing:

JOSM-Icon-move.svg - (S)elect - for selecting elements, viewing/editing their tags, and moving them.

JOSM-Icon-autonode.svg - (A)dd - for adding new nodes to create a new way, extend an existing way, or as a standalone node

Because you will be flipping between these modes quite a lot, it's worth remembering the keyboard shortcuts: S and A.

You will also need to delete things sometimes. The keyboard shortcut is the Delete or Del key (on a mac you must also hold down Fn key)

(By reading , "S" etc. here means 'Upper case "s"', not Shift+S)

Adding a way

When creating a way, you need to think about what is currently selected.

  • Clear your current selection by doing 'Selection' menu -> 'Unselect all'. Alternatively put JOSM into select mode (S) and click somewhere in the black background.
  • With nothing selected, press A to begin adding a brand new way.
  • Click somewhere in black background to create a new node.
  • Keep clicking to draw a way with several nodes in it.
  • When you want to stop adding, press S to go back to select mode.

Adding a stand-alone node

To create a standalone node, repeat the same steps above, but this time we'll stop adding after only one node:

  • Clear your current selection
  • Press A to begin adding
  • Double-click to create the node.
  • Press S to go back to select mode.


Panels appear as a strip on the left hand side of the JOSM screen, but you can show & hide each one. Do this by clicking the various buttons in the bottom-left:


They are toggle buttons, meaning you can click the same button to show the panel and then hide it and then show it again (try it). On the panels themselves, you have the option to minimise them, or un-pin (undock) a panel to have it as a separate window.

Some panels are more useful than others. You'll definitely want to have the "Tags/Memberships" panel visible (JOSM-Icon-propertiesdialog.svg).


Tags are displayed in a panel called "Tags/Memberships" in the top-right. When you select an element, its tags will be displayed there in a table with keys on the left, and values on the right. Go into (S)elect mode and try selecting an existing way or node to see its tags. In the areas of existing map data which you downloaded, you should find a lot of tags. Some tags have quite complicated meanings, while others like the 'name' tag, are quite straightforward. Refer to Map Features for tag documentation (worth having a look at, but it's quite a big list. You're not expected to know all of these tags!)

To add a new tag, click the JOSM-Icon-add.svg Add button (not to be confused with "(A)dd mode" for adding data elements) -- or you can press the keyboard shortcut Alt+A.

To edit an existing tag, double-click on it, or click once to select it and then click the 'edit' button, or you can press the keyboard shortcut Alt+S.

When typing your tag into the key and value boxes, you'll find JOSM snaps to suggested values from a drop-down. This is a time-saving feature based on all keys and values appearing within the downloaded area and all common tags that JOSM knows about.

A note on selecting: When you select elements to modify the tags on, take care to select the right thing. Normally you might only select a single element (a way or a node), but in JOSM you are also able to select multiple elements and apply tags across the entire selection. One approach is to drag a selection box, but for more control over your selections, try holding down the Ctrl key while clicking.

Some nodes have tags on them, while others exist purely for connecting to form ways. Standalone nodes (almost) always have tags on them, meanwhile nodes making up a way may have tags, but often do not. JOSM displays nodes which have tags differently: It either displays an icon which describes the meaning of the tag (e.g. traffic lights) or if JOSM does not recognize the tag combination, the node is drawn as a filled, light blue square.

Upload data

Remember you can #Undo / Discard changes at any time, but what if you're happy with your changes? It's time to upload the changes to the OpenStreetMap server.

Simply click the upload icon JOSM-Icon-upload.svg.

You will be prompted to enter a changeset comment. Write a brief description of what kind of edits you are making. This short comment is recorded along with your changes, and displayed to other people if they are looking through the history displays. It's good to explain why you are making the changes rather than just what you are changing (See also Good changeset comments) but don't worry about it too much. A brief comment will suffice.

The first time you upload, you will also be prompted to enter a username and password as registered on the main website (see Creating an Account). Save this to avoid typing it every time, unless you are sharing a computer.

When you upload to OpenStreetMap you agree to release your data contributions under the OpenStreetMap License. Please only contribute data which you are allowed to release (no copying!). Now it's in the OpenStreetMap database, it's free! Your changes will only appear on the map after a delay. It typically takes a few minutes, but can take longer (See Slippy Map#Tile rendering). While you're waiting, why not do some more editing? It's a good idea to upload your editing work quite regularly.

Error and warning messages

Before uploading any data, JOSM will perform validation and if it detects anything which may indicate problems in the data (almost always) it will present a long frightening list of warnings and errors and ask if you want to proceed with the upload. Relax, quite likely many or most of these problems existed already before you started editing - you did run validate after downloading?

Errors should be fixed before upload - especially if your changes are causing them. However if the errors were already present in the data and you don't know how to fix them correctly it may be better to upload the data as is and ask for help in a forum.

It is important to understand that warnings are just warnings, they should be examined and fixed where possible but never at the cost of introducing wrong data or hackish workarounds. If you don't want or can't fix those immediately you can do it anytime later - run "validate" again in the region.

Possible conflicts during edit

What about conflicts? What if somebody else has been editing in the same area since the time when you downloaded? If you think there is a chance of this (e.g. if you downloaded several hours ago, or if you're editing close to somebody else at a mapping party) then it is good idea to do another download before doing an upload. If new elements have been added, you can review these before uploading. If there is a direct clash with somebody else changing the exact same elements, then JOSM will report "conflicts" and allow you to correct them. Some more details of this are described in JOSM/Advanced editing#Resolving conflicts

Next >>

Once you're familiar with basic editing you might want to learn about some more advanced editing.