Mapbox Streets v6
This tileset reference document includes information to help you use the data in the Mapbox Streets v6 tileset.
Overview
The Mapbox Streets v6 tileset includes geometries and metadata for roadways, terrain, administrative boundaries, building footprints, land use classifications, rail stations, points of interest, and more.
For a complete and documented example of using older Mapbox Streets vector tiles to style a Mapbox Studio Classic project, see the OpenStreetMap Bright project for Mapbox Studio Classic.
OpenStreetMap
Mapbox Streets vector tiles are largely based on data from OpenStreetMap, a free & global source of geographic data built by volunteers. An understanding of the OpenStreetMap data structure and tagging system is not necessary to make use of Mapbox Streets vector tiles, though it's helpful to understand some of the details.
When you publicly use styles or software that use Mapbox Streets vector tiles, you must display proper attribution.
Name fields
There are 7 different name fields for each of the label layers:
Field | Description |
---|---|
name | The name (or names) used locally for the place. |
name_en | English (if available, otherwise same as name) |
name_es | Spanish (if available, otherwise same as name_en) |
name_fr | French (if available, otherwise same as name_en) |
name_de | German (if available, otherwise same as name_en) |
name_ru | Russian (if available, otherwise same as name) |
name_zh | Chinese* (if available, otherwise same as name) |
* The name_zh
field contains Mandarin using simplified Chinese characters for our custom label layers: #country_label
, #state_label
, and #marine_label
. All other label layers are sourced from OpenStreetMap and may contain one of several dialects and either simplified or traditional Chinese characters in the name_zh
field.
OpenStreetMap IDs
Most layers in the Mapbox Streets vector tile source have an osm_id
field. The values for this field are integers based on the IDs assigned to objects in the main OpenStreetMap database.
With raw OpenStreetMap IDs it's possible for two different objects of different types to share the same ID, but the Mapbox osm_id
is modified such that a layer containing a mix of object types will not contain any duplicate IDs. The following modification rules are in place, providing non-overlapping IDs to work with while keeping the original IDs easy to deduce at a glance.
Original OpenStreetMap object | Vector tile geometry | ID transform | Example |
---|---|---|---|
node | point | original + 1015 | 123 → 1000000000000123 |
way | line | none | 123 → 123 |
way | polygon, point | original + 1012 | 123 → 1000000000123 |
relation | line | original + 2×1012 | 123 → 2000000000123 |
relation | polygon, point | original + 3×1012 | 123 → 3000000000123 |
Some objects in the vector tiles are the result of merging multiple OpenStreetMap objects. In these cases, the osm_id
will be based on one of the original IDs (and there is no guarantee about which one). Some objects are not from OpenStreetMap at all, or processed in such a way that the original OpenStreetMap IDs are unknown (for example ocean polygons). In these cases, the osm_id
will be 0
.
Boolean fields
Some fields represent a boolean condition; the value may be either true or false. To keep the vector tiles compact these fields are stored as integers, where 0
= false and 1
= true.
CartoCSS examples:
#admin[dispute=1] { /* boundaries that are disputed */ }
#road[oneway=0] { /* roads that are not one-way */ }
Multiple geometry types
Mapnik vector tiles support multiple geometry types in the same layer. The Mapbox Streets source takes advantage of this for some layers.
A geometry in the vector tile can be one of 3 types:
In CartoCSS you can select one or two of the 3 types by filtering on the special mapnik::geometry_type
property.
CartoCSS examples:
#layer['mapnik::geometry_type'=1] { /* point styles */ }
#layer['mapnik::geometry_type'=2] { /* line styles */ }
#layer['mapnik::geometry_type'=3] { /* polygon styles */ }
Data updates
The current supported version of the Mapbox Streets vector tiles receives regular data updates as new information becomes available and existing information is improved.
Layer | Source |
---|---|
most layers | OpenStreetMap replication feed |
#admin | custom OpenStreetMap processing |
#water (ocean parts) | OpenStreetMap Data |
#marine_label, #country_label, #state_label | custom data |
Layer Reference
#landuse
This layer includes polygons representing both land-use and land-cover.
It's common for many different types of landuse/landcover to be overlapping, so the polygons in this layer are ordered by the area of their geometries to make sure smaller objects will not be obscured by larger ones. Pay attention to use of transparency when styling - the overlapping shapes can cause muddied or unexpected colors.
Classes
The main field used for styling the landuse layer is class
.
Value | Description |
---|---|
agriculture | Various types of crop and farmland |
cemetery | Cemeteries and graveyards |
glacier | Glaciers or permanent ice/snow |
grass | Grasslands, meadows, fields, lawns, etc |
hospital | Hospital grounds |
industrial | Only includes airport areas |
park | City parks, village greens, playgrounds, national parks, nature reserves, etc |
pitch | Sports fields & courts of all types |
rock | Bare rock, scree, quarries |
sand | Sand, beaches, dunes |
school | Primary, secondary, post-secondary school grounds |
scrub | Bushes, scrub, heaths |
wood | Woods and forestry areas |
#waterway
The waterway layer contains rivers, streams, canals, etc represented as lines.
Waterway classes can represent a wide variety of possible widths. Since larger rivers and canals are usually also represented by polygons in the #water layer, make your line styling biased toward the smaller end of the scales.
Classes and types
The waterway layer has two fields for styling - class
and type
- each with similar values.
Value | Description |
---|---|
river | Everything from the Amazon down to small creeks a couple meters wide |
canal | Medium to large artificial waterway |
stream | Small waterway, usually no wider than a meter or two |
stream_intermittent | Class only. A stream that does not always have water flowing through it. |
drain | Medium to small artificial channel for rainwater drainage, often concrete lined. |
ditch | Small artificial channel dug in the ground for rainwater drainage. |
CartoCSS example:
#waterway {
[class='stream'], [class='stream_intermittent'] {
line-color: #ace;
line-width: 2;
}
[class='stream_intermittent'] { line-dasharray, 4, 2; }
}
#water
This is a polygon layer with no differentiating types or classes. The tileset filters and simplifies water bodies according to scale. It only shows oceans and large lakes at the lowest zoom levels, while smaller and smaller lakes and ponds appear as you zoom in.
Water polygons sometimes have overlapping pieces with each other, so avoiding CartoCSS styles such as polygon-opacity
and most polygon-comp-op
values is recommended. Instead, use the style-level properties opacity
and comp-op
.
Drawing outlines on water can be tricky. Since rivers and lakes are often broken into multiple pieces you can end up with seams in the middle of water bodies. A common CartoCSS pattern to avoid this is this blur method to create an inner-glow effect:
CartoCSS example:
#water {
::shadow { polygon-fill: #07f; }
::fill {
// a white fill and overlay comp-op lighten the polygon-fill from ::shadow.
polygon-fill: #fff;
comp-op: soft-light;
// blurring reveals the polygon fill from ::shadow around the edges of the water
image-filters: agg-stack-blur(2,2);
}
}
#aeroway
The aeroway layer includes both lines and polygons representing runways, helipads, etc.
Types
The type
field separates different types of aeroways for styling.
Value | Description |
---|---|
runway | Where planes take off & land |
taxiway | Where planes move between runways, gates, and hangars |
apron | Where planes park, refuel, load |
helipad | Where helicopters take off & land |
#aeroway {
['mapnik::geometry_type'=2] {
line-color: #888;
[type='runway'] { line-width: 3; }
}
['mapnik::geometry_type'=3] { polygon-fill: #888; }
}
#barrier_line
This layer includes lines and polygons for barriers - things such as walls and fences.