OpenStreetMap’s web-based iD editor is the easiest and most convenient way to get started mapping. But there may come a time when you need more power – our mapping team uses the Java OpenStreetMap (JOSM) editor every day. JOSM allows you to map fast with keyboard shortcuts, a series of editing tools for common tasks and specialized plugins. Here is your guide to take your mapping skills to the next level.

Getting started

The JOSM editor runs directly on your desktop. Make sure you have the Java Runtime installed and install the latest version of JOSM. Connect a two-button mouse to your computer to make working with JOSM easier.

Loading data

After starting JOSM, the first step is to download the area you want to map. Click the download button (green arrow) in the upper left, this opens the download dialog.

Find a place you’d like to map by panning with the right click of your mouse and zooming in and out of the map with your mouse scroll wheel. Drag the left mouse button to draw a box around the area you want to map. Once you’ve selected an area, press the “Download” button at the bottom. When the download is complete you will see OpenStreetMap data in the main editing window. Next, load satellite imagery to assist with identifying objects on the ground. Select “Imagery” from the menu bar and choose a satellite layer of your choice.

Select an area of interest and download it from OpenStreetMap for editing.

Panning and zooming in the editor window is similar to the operations in the download dialog. At the top right of your editing area is the “Layers” window. The data you have downloaded and the satellite imagery you have chosen are presented as different layers. You can control the visibility and the order of the layers with the options available here.

Understanding data

In order to work with JOSM it’s very useful to understand OpenStreetMap’s data structure. Simply speaking, OpenStreetMap is made up of nodes (points) and ways (lines). Each point in a way is a node itself. Nodes and ways are attributed with tags that specify their meaning. An ATM for instance would be a node with the tag amenity=atm. A train station would be a node with the tag railway=station. A residential road would be a way with the tag highway=residential and a building would be a closed way with the tag building=yes and so on.

Once you’ve tagged an object, JOSM indicates it with special symbols or in special colors - for example, a coffee cup to show a coffee shop, tree figures for trees, blue lines for rivers, and pink areas for buildings.

Nodes with symbols for trees, cafés, water fountains, restaurants in JOSM.

Ways representing roads. Different colors represent different functional road classes.

Closed ways representing buildings (pink), a playground (yellow), a school ground (yellow) and two ponds (blue).

To explore features, click on the “Select” tool — the first tool in the vertical edit tools bar on the left. When you select an object, a panel appears to the right of the map titled “Tags/Memberships”. Tags are represented as a key-value pair. The key represents a broad feature category while the value is the specific type of feature.

Tag combinations for different features.

Editing data

Try improving the accuracy of a feature. For example, a road may be misaligned and can be adjusted. Select the road and drag it where it should be.

Aligning a road.

If you find missing features, such as a road or a point of interest, you can add it using the “Draw” tool — the second tool in the vertical edit tools bar on the left. To switch fast between selecting and drawing use the keyboard shortcut “s” for select mode and the keyboard shortcut “a” for draw mode.

Let’s add a point of interest, say a restaurant. Select the Draw tool from the edit tools and move to the location of the restaurant. Click on the location of the place to add a new node. From the “Tag” window, click on the “Add” button. A pop-up window appears prompting you to select a “key” and a “value.” Select the key “amenity” and the value “restaurant” and confirm with “OK” - you’ve mapped your first feature!

Now, try adding a road. Switch to Draw mode, with the satellite imagery as your reference, zoom to a residential neighborhood and click at the point where a road begins. From there move the mouse and click again where the road ends in the satellite imagery. Switch to Select mode, click on the line representing the road and add the tag highway=residential. Add the name of the road if you know it by using the name tag.

When adding roads, always connect them to existing roads. This is important because it allows software, like routing engines, understand the logical road network. To connect a new road to another existing road, begin drawing by clicking on an existing road. To disconnect roads, select the node (point) connecting the road ways and select “Unglue Ways” from the “Tools” menu.

With the road in place, let’s add a building to the map. Use the Draw tool to draw a closed way where the last node connects with the first node in the way. Then add the tag building=yes and observe how JOSM turns the inside of the closed way a semi transparent pink.

Adding points of interest, roads and buildings.

Uploading your data

Once you’ve finished mapping, save your data to OpenStreetMap using the “Upload” button in the top left. Add a comment describing your work — for instance “New roads and features in my neighborhood.” — and specify your source — for instance “Imagery and local knowledge”. If this is your first upload, JOSM will ask you to enter your OpenStreetMap account details. If you don’t have an account yet, create one on OpenStreetMap.org.

JOSM validates your data before upload and provides you with warning and error messages to keep your data clean. Make sure to fix issues before confirming your upload.

Once you’ve uploaded your changes, they will become visible on OpenStreetMap.org’s map within minutes.

You’re on your way with the mapping power of JOSM. To learn more, dig into our mapping guides.

Happy mapping!