Mapbox OpenStreetMap

OpenStreetMap is the free and editable map of the world, created and maintained by a huge international community. Mapbox Streets, our customizable map layer of streets, buildings, and places from all around the world, is powered by open data from OpenStreetMap. Anybody can create an account and start editing on within minutes.

Our data team updates OpenStreetMap based on quality analysis and customer feedback. Our principle is to work in the open, these mapping guides are primarily consolidated and maintained by our data team for various mapping projects and on-boarding new team members.

You are welcome to join one of our open mapping projects over on the issue queue and use these best practice mapping guides. These guides are licensed under Public Domain (CC0), if you would like to contribute or have an feedback on these, please feel free to raise an issue in this repository.

Mapping with JOSM

Mapping guides

Mapping with JOSM

This guide will get you started mapping with the Java OpenStreetMap editor (JOSM) - a powerful and popular desktop editor for OpenStreetMap. Another popular editor is iD, commonly used for short and simple, browser based editing sessions. Note that this section only focuses on the mechanics of editing with JOSM.

Downloading from OpenStreetMap

To start editing, download an area from OpenStreetMap by using the green down-arrow button on the left in the menu bar.

Using imagery

You will routinely use imagery for mapping. JOSM comes with a variety of pre-configured satellite imagery layers - the Bing and Mapbox layers being the most popular ones. Bing and Mapbox may have different levels of detail and clarity in different places, so often worth checking both. Simply select one of them from the imagery menu and you’re ready to go.

When using imagery, keep in mind that imagery may be offset. That is, due to complexities in processing satellite imagery, features on imagery may not be at the same location as they are in the real world. For reference, check existing features on the map and compare them with the imagery or download GPS tracks. To download GPS tracks from OpenStreetMap, check the “Raw GPS” box in the download dialog. If you observe an offset in the imagery, you can correct for it by selecting the “New offset” item in the “Imagery” menu.

Creating data

Click the “Draw nodes” button to enter the data creation mode. Subsequent clicks on the map will set nodes connected by a way. Double click to finish drawing the way. For drawing single nodes, simply double click on the map. To draw a closed way, finish a way with a click on the first node you drew.

Modifying data

Click the “Select” button to select existing nodes or ways. To move nodes or ways click on them, hold the mouse button pressed and drag them. Then release the mouse button where you’d like to drop them.

To delete data, use the del key of your keyboard or on a mac, use fn+delete.

If you ever make a mistake, ctrl+Z, or command+Z on mac, will undo the last change.

Ways can be connected to each other. In JOSM speak, you can glue, unglue, split and combine them. This is useful to create logical connections, for instance between roads of different type. To prevent ways from connecting when drawing, say when drawing a road close to buildings, hold the ctrl key, while clicking the mouse.


You can add, modify or delete tags directly in the tagging panel in JOSM’s side bar. If for some reason this panel is not visible, you can enabled it under the “Windows” menu. The example below tags two ways at the same time. Simply hold shift to select multiple objects.

screenshot from 2014-11-24 16 15 10

Presets are common tags or tagging combinations that can be applied to objects. They can be found in the “Presets” menu where they are organized into logical categories. Try adding a preset and then review the modifications in the tagging panel.


** Copy & pasting tags **

You can copy and paste tags from one object to another. Just select one object, copying with ctr + c. Then select the other object and paste with ctrl + shift + v. This will copy only tags - not the geometry.

Uploading to OpenStreetMap

To upload the data, click on the green up-arrow button on the left in the menu bar. This will automatically trigger validation. Review all validation warnings and resolve all errors before you upload. If there are any errors or warnings, do your best to fix them. Before you upload, add a proper changeset comment and specify what source you used. This is important as it will show other users who see your changesets what this changeset was intended to modify and from where you took the information.

The upload will take a few seconds. The data is live on OpenStreetMap immediately. The map usually takes a couple of minutes to clear through all caches.

Once you uploaded the data, you and everyone else can see a corresponding entry on your OpenStreetMap user profile under “My Edits”:

Productivity tips


Filters are very powerful and can speed up your work tremendously. Take a look at the JOSM filter documentation and at AJ’s blog post about filters to learn how they work.

Here are some of the most common filter selectors in use for editing:

boundary: | leisure: | landuse: | waterway: | amenity: | natural: | building:

Pull out common highway classifications into toolbar

When you work on OpenStreetMap, you will use highway classifications a lot, bring them all into the toolbar:

screenshot from 2014-11-24 15 59 41

Use keyboard shortcuts

When you’re editing, you will be a lot faster using keyboard short cuts. Take a moment to familiarize yourself with them and start using them! You can find keyboard shortcuts in the menus like in the screenshot below, but there’s also a full reference of keyboard shortcuts on the JOSM web site (en español).

screenshot from 2014-11-25 22 25 06


There are many JOSM plugins that will help you to map faster. Here are a couple that used most commonly. You find all plugins in the settings panel:

Buildings plugin

For tracing buildings, always use the buildings plugin. It speeds up editing by creating rectangular boxes with a tag building=yes by default. To quickly draw buildings that are aligned to each other, draw the first building, select it, and draw subsequent parallel buildings.

To align existing buildings neatly, you can select multiple buildings, then two extra nodes to set the alignment axis and orthoganalize shape (keyboard shortcut q)


turnrestrictions plugin

This plugin makes it really easy to add turn restrictions such as “no left turn” to roads.

edit a new turn restriction in layer data layer 1 2015-12-11 17-02-26

Read more in JOSM help -

Fast draw plugin

This plugin is great for tracing areas like forests, lakes, waterways or landuse and linear features like roads.

To start, press shift + f, then click with the mouse to start drawing. Whenever you’d like to set a node, press the space bar. For free hand drawing, keep the space bar or mouse button pressed.


To delete the latest created nodes, just hit backspace.

To determine how many nodes are set automatically in freehand mode, use the up and down arrow keys.

To finish drawing, press enter to go into the simplification mode (feature will turn yellow), press the up or down arrow for the desired level of simplification and press enter again to create the way.

While tracing you can press Q to set some preferences for “FastDraw”

fastdraw configuration 2015-12-14 22-55-16

Video Tutorial


Utilsplugin2 comes with a series of tools that you can all find in the new menu “More tools”, after the plugin is installed. The most used one is “Add nodes at Intersections” which gives you a fast way to add nodes at places where ways intersect in the current selection.

screenshot from 2014-11-25 17 03 51

Video Tutorial


Notes are a great way to post questions for others on the map. When mapping, observe notes that others left in the area and if you have a specific question or a suggestion on how the map could be improved, consider leaving a note.

Activate the notes plugin:

screenshot from 2014-11-25 16 49 25

Now you should see a list of notes in the side bar for the area you’re mapping in:

screenshot from 2014-11-25 16 52 11


JOSM automatically validates your data when uploading, but you can run validation at any point by clicking ‘Validation’ in the Validation panel.

Configuring drawing styles

Sometimes it’s useful to tweak drawing stiles to help improve visibility of certain features.

For example, if you’re working with addresses, activate “Address Tags Validator”:

screenshot from 2014-11-25 15 10 03

Or if you’d like to see clearly what you’ve edited in your session, activate “Modified objects”:

screenshot from 2014-11-25 15 13 59

Try different drawing styles yourself and figure out which ones help you do your work better.

Highlight data freshness

You can use this style to highlight features that are created or modified in 2016. To configure this:

Custom imagery

You can also add custom imagery from Tile Map Service (TMS) or Web Map Service (WMS) endpoints. Here is how:

Resolving conflicts

If you upload a change to OpenStreetMap and someone has changed one of the same features in the meantime, a conflict will occur. In this case OpenStreetMap will refuse your changes. Follow these steps to resolve the conflicts:

  1. Download new data from OpenStreetMap for the area in which the conflict occured.
  2. Run validation and review the conflicts.
  3. Fix them.
  4. Attempt upload again.

As a last resort, you can attempt to upload changes one by one. This is not recommended though.

screenshot from 2014-11-25 16 43 40

Scripting JOSM

You can script JOSM to automate certain workflows. For example:

  • Expand abbreviations (US):
  • Capitalize names and eliminate “name=S/N”:
  • Expand abbreviations (Peru):


Further reading and questions

For further information, take a look at the JOSM help.

This is the last guide in this category.