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.

Getting started

Mapping guides

Getting started

To get started editing OpenStreetMap using JOSM, set up your work environment with the tools you would need.

Setting up an OpenStreetMap Account

  1. Go to and create an account:
  2. IMPORTANT add a picture of yourself to your profile.
  3. Add a profile description like below:

Profile description

It is useful to include:

  • The areas you are interested in mapping;
  • A nice message that allows others to get in touch;
  • Links to your homepage/twitter etc that allows people to follow you.

(format in Markdown)

Here is a good example:


Installing JOSM

We are using the Java OpenStreetMap Editor (JOSM) for most tasks. Here’s how to get set up.

1. Download and install JRE

JOSM requires the Java Runtime Environment - JRE. Download and install JRE.

2. Download JOSM

Go to the JOSM website to download the tested version. Place it in a common location for applications on your operating system.

  • OSX: /Applications/
  • Windows: C:\Program Files\

3. Open JOSM

Open the JOSM application you downloaded with a double click.

If you want JOSM to use more memory and you’re using Linux you can also run it with:

~$ java -Xmx1024M -DproxyHost=$PROXY -DproxyPort=8080 -jar josm-tested.jar

Once JOSM is up and running it looks like this. Go find the Preferences dialog, you’ll need it for the next couple of steps. You can access it from under the light switch icon.


4. Enable expert mode

Open the Preferences dialog and enable Expert mode.


5. Add user and password

Now it’s time to connect to OpenStreetMap. Add the user name and password of the account you created on OpenStreetMap to JOSM.


Now you should be able to retrieve data from OpenStreetMap by clicking on the button with the green down arrow in the top left:


6. Enable Remote Control

Remote control allows you to launch JOSM directly from the map on To enable Remote Control, check this box in the settings:


Also check the Download objects to a new layer option. Now you should be able to retrieve data directly starting on like this:


7. Increasing the allocated memory for JOSM

By default JOSM is allocated with 247-1024 MB of memory depending on the operating system. When JOSM reaches its maximum handling limit it pops up an error highlighting JOSM is out of memory

increasing memory

To get rid of this error increase the default allocated memory for JOSM by following these steps. If you are not sure of fixing this, do contact someone from the data team.

Using a gaming mouse

Using a gaming mouse can increase your productivity by assigning shortcuts to common mapping tasks. This section outlines the basic configuration to use a gaming mouse in JOSM.

Systems: Linux and Mac

Equipment: Razer Gaming mouse

General guidelines: Increase mouse speed in System Preferences> Mouse for Mac

Example Feature


Configure gaming mouse and keyboard

  1. Install Razer Naga config software:
  2. Create an account in razer ID:
  3. Build your profile using your email id
  4. Configure the mouse:

Common shortcuts essential to configure in your gaming mouse for buildings: Enter, Extrude (X), building tracing (B), upload and download data to OSM (use the default keyboard shortcuts in your JOSM).

Good to have: Join and merge nodes/ways (J and M), select overlapping ways (I), join overlapping areas (Shift + J), Split objects (Alt + X)

Note: Pattern to follow in setting up your mouse:

Left hand (shortcuts in the keyboard):

  • Upload

  • Select

  • Orthogonalize

  • Rotate

Right hand (shortcuts in your mouse):

  • Enter

  • X

  • B

  • Merge two nodes(M)

  • Join node to way (N)

  • Select intersecting ways (I)

  • Join overlapping ways (shift+J)

Configure any other shortcut according to the mapper choices.

Note: For mapping other features like roads and to fix task, create separate configurations with the shortcuts required only for those features.

This is the last guide in this category.