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 common features

Mapping guides

Mapping common features

This is a walkthrough of how to create and edit the most common features on OpenStreetMap. It’s an introduction to get you started mapping but not meant to be comprehensive. We’re going to use some OpenStreetMap specific terms here, if you’re not familiar with what “nodes”, “way” and “relations” are, read the previous guides first.

How do I map X?

We’re focusing in this section on the most common map features. For full documentation, refer to the OpenStreetMap Map Features guide or Feature categories. To look up a specific map feature fast, for instance how to map a bus stop, google with a query like “tag bus stop”:

A valuable complimentary resource is Tag info shows you the number of times a specific tag has been used, which lets you find out how established a tag is.

Roads and paths

Roads are some of the most significant features we map. While roads are easy to trace off of Satellite imagery there is a large vocabulary for classifying different types of roads.

Tracing roads

Tracing a road is simple. Use the Draw (A) tool in JOSM or the Line tool in iD and draw the road following its course. The trick is to use the right amount of nodes to describe a way. Too few make the road appear very jagged. Too many are unnecessary data and make the road hard to edit later.

Look at the picture below, the first example was traced with too few nodes, it is too jagged; the second example was traced with too many nodes adding redundant information; the last one is traced right:

mapbox guide big

Roads must be connected where they intersect. On the left you can see two roads just crossing each other, on the right note how a node connects the two roads. This is important for navigation, where vehicles must be guided from one road to the other.

And follow the flow of roads where possible. On the left, the road was traced with a “detour” for no apparent reason. On the right you see how the road tracing follows the logical flow of the road.

wrong: "map around corners", right: follow flow

Trace every physically separated lane as a separate way. See for example this dual carriage way (orange):

dual carriage way

When mapping a dual carriage way, make sure that connecting roads are properly connecting to both carriages if this connection is possible in reality:

show 2 examples of connecting roads to a carriage way: one connecting to both lanes, one to only one lane

Everything’s a highway

No matter whether it’s an overland road, a city street, a foot path or a cycleway, you’ll find it tagged with the highway key. Here are some examples of common tags:

  • highway=residential - a residential road in a city
  • highway=motorway - a fast restricted access road
  • highway=footway - a foot path
  • highway=cycleway - a cycleway

Roads often come with secondary tags, further specifying type or attribute of a road:

  • oneway=yes says a road is a one way
  • lanes=2 says how many lanes a road has
  • name=Broadway designates a street name
  • access=private|permissive describes the level of access on a road
  • service=parking_aisle|driveway further specifies the type of highway=service


Oneways are mapped by simply adding a oneway=yes tag to the road’s way. Keep in mind that ways have a directionality. So the road will be a oneway in the direction of the way. If you need to change the flow of the one way, you have two options:

  • Change the direction of the way (Tool > Reverse Ways in JOSM or the << context icon on iD)
  • Or tag with oneway=-1 - use this approach where the way’s directionality already governs another attribute such as bus route.

tagging a oneway

OpenStreetMap Wiki: Key:oneway

Turn restrictions

Turn restrictions are rules that disallow certain turn maneuvers. Here’s for instance a “no right turn” sign.

To map turn restrictions in JOSM, use the turnrestrictions plugin. Once enabled, you can activate a new turn restriction panel from the Windows > Turn Restriction menu item.

Once enabled, create new turn restrictions or edit existing ones from the panel. Here is an example of how to create a simple “no right turn” restriction. We’re selecting the way we can’t take the right turn from as “from” object, the way we can’t take the right turn to as “to” object and then we specify that the restriction is a “no right turn” restriction. As we save the turnrestrictions dialog warns us that there is no “via” object defined. It is not strictly required to have one, but is good practice, so we define one.

Turn restrictions can get more complex quickly, so before you create or edit turn restrictions, make sure you read through and understand all available documentation on the OpenStreetMap wiki.

Video: How to edit turn restrictions in JOSM

OpenStreetMap Wiki: Relation:restriction

Simple classification guide

One of the more subtle skills to learn in OpenStreetMap is how to properly classify roads. The highway tag has more than eight values for roads, another five-plus for non-vehicular traffic, and a series of secondary tags. What’s more, highway classifications are highly country specific and follow different conventions on a country by country basis.

Here’s a quick guide on how to go about working with road classifications in OpenStreetMap.

  1. Follow existing classifications. Don’t change classifications and follow the conventions you see on the local map for new data.
  2. The smallest roads in a network are the easiest ones to identify and also the ones you’ll wind up adding most. For minor roads, prefer highway=residential in built up residential areas, highway=unclassified for everything else.
  3. For all other cases, use highway=road

For a full reference on highway mapping, look at the wiki entry for the highway tag.


The intersection between a road and another feature must always be defined. Where they meet, there is either an intersection, a tunnel or a bridge.

Simple intersections between two roads

To create a simple intersection between two roads, just make sure to connect the two roads with a node.

show how 2 roads connect


A tunnel carries the tunnel=yes and a layer= tag that is one lower than the layer= tag of the feature it intersects with (default layer value is 0). The road is not connected with the other feature. Split ways where the tunnel starts

show how to map a tunnel

A building passage is a special type of tunnel that passes through a building. To map a building passage, connect the road where it intersects with the building outline with nodes, then tag the portion of the road that intersects with the building with tunnel=building_passage.

map a building passage

OpenStreetMap Wiki: Key:tunnel


In addition to the road’s highway=* tag, a bridge carries the bridge=yes and a layer= tag that is one higher than the layer= tag of the feature it intersects with (default layer value is 0).

show how to map a bridge

OpenStreetMap Wiki: Key:bridge

Railroad crossing

Map a railroad crossing similar to an intersection between two roads by connecting the road and the railroad with a node. Then tag the node with railway=level_crossing. Do not confuse this tag with railway=crossing which is only for pedestrian crossings.

map a level crossing

OpenStreetMap Wiki: Tag:railway=level_crossing


Map a roundabout by tracing the circular road and tag it with junction=roundabout. For the road classification, use the highest classification of all roads connected to the roundabout. The junction=roundabout tag implies a oneway - make sure that the directionality of the way is correct.


Complex intersections

In a complex intersection involving multiple carriage ways trace the roads so that they reflect the flow along the main carriages and make sure that oneways make sense.


Tracing buildings takes good imagery and patience. Take your time and pay attention to angularity, alignment between buildings and reflecting the regularities between buildings. Buildings are traced as outlines of where the building meets the ground. This last piece is important. The roof outline is often easier to see in the imagery so you’ll find it often traced in OpenStreetMap but it’s wrong and needs to be shifted to the ground outline.


The main challenge with tracing buildings is lack of detail in imagery. Where you don’t find good enough imagery for tracing a building, just don’t trace it.

Here are a couple of JOSM specific tips to trace buildings effectively.

For tracing buildings, use the buildings plugin. Once enabled, a new building tool will be available in the edit toolbar on the left. The building tool B will draw rectangular shapes tagged building=yes for you. To draw buildings parallel to each other, draw the first building, select it, then draw subsequent buildings.

If you draw closed ways free hand, use Tools > Orthogonalize Shape or press Q to square out buildings like so:

Use auxiliary lines to align protruding portions of a building:

To align previously traced buildings neatly, select them, and then select two reference nodes to create an alignment axis and orthoganalize Q the selection.


You can use split buildings temporarily with Tools > Split Way or pressing P to orthogonalize portions of a building before reconnecting the with Tools > Connect Way or pressing C:

Here is a quick end to end walkthrough of how to trace a building:

OpenStreetMap Wiki: Key:building

Video: Tracing buildings with JOSM

Points of interest

“Point of interest” is a general term for a real world point-like feature noteworthy enough to include it on a map. Some examples are restaurants, cafés, shops, banks, churches, public toilets and water fountains. There’s not a single point of interest tag key in OpenStreetMap but a variety that can be used for mapping a point of interest: amenity=, shop=, tourism= are some examples.

OpenStreetMap Wiki: Key:amenity, Key:tourism, Key:shop, Key:leisure

Simple point of interest

The simplest way to map a point of interest is to create a single node and add corresponding tags. Here’s an example of a fountain mapped in OpenStreetMap:

Here’s an example of a restaurant:

Areas as points of interest

Wherever you can clearly determine the extent of a “point” of interest, map it. A good example are parks, here is Folger Park in Washington DC. The Park is mapped as a closed way tagged leisure=park. Note how the way follows the exact outline of the park.

Building as point of interest

Sometimes the building itself is considered the point of interest. Think for instance of a MacDonalds restaurant in an urban multi-use building versus a MacDonalds drive through in a suburban strip mall. Or - often easy to spot from satellite imagery - think of a place of worship like a church. In such cases the building itself should be tagged as a point of interest. Here’s a church that has first been mapped as a single node in a building. The example shows how all tags from the node are transferred to the building and then the node is removed.

Schools and universities

Schools can just be mapped as a simple node tagged amenity=school. But often schools occupy an entire building or a piece of land. School grounds, the terrain on which a school sits, are mapped as amenity=school. The buildings of a school are mapped as building=school. Mapping schools as just a simple node is fine. However, wherever appropriate, map a school’s ground and buildings as ways.

An example where a school does not occupy the entire building:

An example where a school does occupy an entire building:

An example where a school occupies its own school grounds:

Universities are similar:

OpenStreetMap Wiki: Tag:amenity=school, Tag:building=school, Tag:amenity=university, Tag:building=university, Tag:amenity=college

Streams and Rivers

Trace small streams as just a way tagged with waterway=stream. The way’s direction signals the direction in which the water flows. For larger rivers, trace the center of the river as waterway=river and in addition the river banks with natural=water and water=river tags. The name of the river always sits on the waterway. See here for an example:

Islands in rivers are mapped as relations of type=multipolygon. Observe how on a multipolygon the natural=water and water=river tags sit on the multipolygon relation and not on the way:

Video: Map a river island

OpenStreetMap Wiki: Tag:waterway=river

Coming soon

  • Walking and cycling paths
  • Places (city versus village versus suburb versus neighborhood)
  • Lakes
  • Tracing highway areas

This is the last guide in this category.