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.

The OpenStreetMap data model

Mapping guides

The OpenStreetMap data model

In OpenStreetMap, each feature is described as one or more geometries (think for instance of a river’s shape) with attached attribute data (think of the river’s name). Geometries are described with three different elements: nodes, ways and relations. Attributes are described as tags that can be part of a node, a way or a relation.

Nodes are the equivalent of a point, ways are like lines that connect points and relations are collections of points or ways that represent a larger whole. This is easiest to understand with a couple of examples.


Nodes are used to represent any kind of point type feature or just to designate a name for a point of interest in the vicinity. Here’s a node representing a café:


and here’s one representing New York City:



A way is a line feature connecting two or more nodes - like a road here:


If you close a way - by connecting its end to its start, you can map area type features like this building here:


or this park:


Nodes are usually just the items that define a way. But nodes sitting on a way can have their own significance. In this example the node is part of 10th Street and M Street and it also denotes that there’s a traffic light.



Before we hop to the third element next to nodes and ways - relations, let’s look at tags. You’ve seen them now already a couple of times in the examples above, like in this café node:


Any point type feature is a node. Whether the node designates a café, a school, a fire hydrant, a tree, a park, a mountain peak is entirely up to how the node is tagged. Any line type feature is a way. Whether the way is a road, a building, a lake, a railway, a cycleway is again, defined by how it is tagged.

Tags can be on any element: on nodes, ways and relations.


Relations are used to organize multiple nodes or ways into a larger whole. Take here for instance the bus route 23 running through 3 different ways.


The type of relation that you’ll probably deal most with describes an area with punched out holes - a so called multipolygon. Here is an example of a multipolygon building with a yard. It consists of 2 ways with each multiple nodes. One way describes the outer wall of the building, the other one the inner wall. The ways are part of a relation of the type type=multipolygon, the outer way has the role outer and the inner way has the role inner. Note: the building=yes tag is on the relation (not on the way).

Your OpenStreetMap editor will take care of creating multipolygons for you so don’t worry if this seems dense for now. If you need to fix a multipolygon, this is a good section to come back and review.


Further reading

To learn more about the OpenStreetMap data structure, take a look at these resources:

This is the last guide in this category.