Mapbox Streets v5

Source id:
mapbox.mapbox-streets-v5
warning
Update to Mapbox Streets v8

We recommend moving to Mapbox Streets v8 for additional features and improvements. Mapbox Streets v5 no longer receives data updates from OpenStreetMap.

This is an in-depth guide the data inside the Mapbox Streets vector tile source to help with styling. For a complete and documented example of using Mapbox Streets vector tiles to style a Mapbox Studio Classic project, see the OpenStreetMap Bright project for Mapbox Studio Classic.

Overview

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 uses Mapbox Streets vector tiles you must display proper attribution.

Name fields

There are 5 different name fields for each of the label layers:

FieldDescription
nameThe name (or names) used locally for the place.
nameThe name (or names) used locally for the place.
name_enEnglish (if available, otherwise same as name)
name_esSpanish (if available, otherwise same as name_en)
name_frFrench (if available, otherwise same as name_en)
name_deGerman (if available, otherwise same as name_en)

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 simple to deduce at a glance.

Original OpenStreetMap objectVector tile geometryID transformExample
nodepointoriginal + 1015123 → 1000000000000123
waylinenone123 → 123
waypolygon, pointoriginal + 1012123 → 1000000000123
relationlineoriginal + 2×1012123 → 2000000000123
relationpolygon, pointoriginal + 3×1012123 → 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:

Point
Linestring / multilinestring
Polygon / multipolygon

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.

LayerSource
most layersOpenStreetMap replication feed
#admincustom OpenStreetMap processing
#water (ocean parts)OpenStreetMap Data
#marine_label, #country_label, #country_label_line, #state_labelcustom data

Layer Reference

#landuse

buffer: 4

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.

ValueDescription
agricultureVarious types of crop and farmland
cemeteryCemeteries and graveyards
glacierGlaciers or permanent ice/snow
grassGrasslands, meadows, fields, lawns, etc
hospitalHospital grounds
industrialOnly includes airport areas
parkCity parks, village greens, playgrounds, national parks, nature reserves, etc
pitchSports fields & courts of all types
rockBare rock, scree, quarries
sandSand, beaches, dunes
schoolPrimary, secondary, post-secondary school grounds
scrubBushes, scrub, heaths
woodWoods and forestry areas

#waterway

buffer: 4

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.

ValueDescription
riverEverything from the Amazon down to small creeks a couple meters wide
canalMedium to large artificial waterway
streamVery small waterway, usually no wider than a meter or two
stream_intermittentClass only. A stream that does not always have water flowing through it.
drainMedium to small artificial channel for rainwater drainage, often concrete lined.
ditchSmall 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

buffer: 8

This is a simple 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:

#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

buffer: 4

The aeroway layer includes both lines and polygons representing runways, helipads, etc.

Types

The type field separates different types of aeroways for styling.

ValueDescription
runwayWhere planes take off & land
taxiwayWhere planes move between runways, gates, and hangars
apronWhere planes park, refuel, load
helipadWhere helicopters take off & land

CartoCSS example:

#aeroway {
  ['mapnik::geometry_type'=2] {
    line-color: #888;
    [type='runway'] { line-width: 3; }
  }
  ['mapnik::geometry_type'=3] { polygon-fill: #888; }
}

#barrier_line

buffer: 4

This layer includes lines and polygons for barriers - things such as walls and fences.

Classes

ValueDescription
cliffThe precipice of a vertical or steep drop
fenceInclude various types of fence and wall barriers
gateOnly gates that are lines or areas are included
hedge
landIncludes breakwaters and piers

Cliff data from OpenStreetMap is designed such that the left-hand side of the line is the top of the cliff, and the right-hand side is the bottom. See the Line patterns with images section of the TileMill Styling Lines guide for how to design an appropriate image pattern for cliffs.

CartoCSS example:

#barrier_line[class='fence'] { line-color: #864; }
#barrier_line[class='hedge'] { line-color: #aec; }

#building

buffer: 2

This is a simple polygon layer with no differentiating types or classes. Large buildings appear at zoom level 13, and all buildings are included in zoom level 14 and up.

CartoCSS example:

#building {
  polygon-fill: #eca;
  line-color: #864;
}

#landuse_overlay

buffer: 4

This layer is for landuse / landcover polygons that your style should draw above the #water layer.

Classes

The main field used for styling the landuse_overlay layer is class.

ValueDescription
wetlandWetlands that may include vegetation (marsh, swamp, bog)
wetland_novegWetlands that probably don't contain vegetation (mud, tidal flat)

CartoCSS example:

#landuse_overlay[class='wetland'] {
  polygon-pattern-file: url("./icons/wetland.png");
}

#tunnel, #road, #bridge

buffer: 4

The roads layers are some of the most complex ones in Mapbox Streets. Starting at zoom level 12, the tileset breaks tunnels and bridges out of the #road layer into either #tunnel or #bridge.

Classes

The main field used for styling the tunnel, road, and bridge layers is class.

ValueDescription
motorwayHigh-speed, grade-separated highways
motorway_linkInterchanges / on & off ramps
mainTrunk, primary, secondary, and tertiary roads & links lumped together for simpler styling.
streetStandard unclassified or residential streets
street_limitedStreets that may have limited or no access for motor vehicles. Pedestrian streets, roads under construction, private roads, etc.
serviceAccess roads, alleys, agricultural tracks, and other services roads.
drivewayFor local access. Includes parking lot aisles, public & private driveways
pathFoot paths, cycle paths, ski trails.
major_railRailways, including mainline, commuter rail, and rapid transit.
minor_railYard and service railways.
aerialwaySki lifts, gondolas, and other types of aerialway.
golfThe approximate centerline of a golf course hole

One-way roads

A oneway field indicates whether the motor traffic on the road is one-way or not. If the road is one-way, traffic travels in the same direction as the linestring.

CartoCSS example:

#road[oneway=1] {
  marker-file: url(shape://arrow);
  marker-fill: red;
}

Types

The type field is the value of the road's "primary" OpenStreetMap tag. For most roads this is the highway tag, but for aerialways it will be the aerialway tag, and for golf holes it will be the golf tag. See TagInfo for a list of used tag values.

Layers

The layer field is used to determine drawing order of overlapping road segments in the tunnel and bridge layers. 95% of values are -1, 1, or 0, and 99.9999% of values are between -5 and 5.

If you want to make sure proper ordering of overlapping bridges when dealing with styles that involve road casing, you'll need to manually add some extra code to your project.yml. The layer field is intended to be used by this feature, not in your CartoCSS styles directly.

project.yml:
_properties:
  bridge:
    "group-by": layer
    # ...

#admin

buffer: 4

Administrative boundary lines. These are constructed from the OpenStreetMap data in such a way that there are no overlapping lines where multiple boundary areas meet.

Administrative level

The admin_level field separates different levels of boundaries, using the same numbering scheme as OpenStreetMap. See admin_level for details about what the different values translate to in different countries.

ValueDescription
2countries
3regions (not commonly used)
4states, provinces, etc.

Disputes

The disputed field should be used to apply a dashed or otherwise distinct style to disputed boundaries. No single map of the world will ever keep everybody happy, but acknowledging disputes where they exist is an important aspect of good cartography.

CartoCSS example:

#admin[admin_level=2] {
  line-width: 2;
  [dispute=1] { line-dasharray: 4, 4; }
}

Maritime boundaries

The maritime field can be used as a filter to downplay or hide maritime boundaries, which are often not shown on maps. Note that the practice of tagging maritime boundaries is not entirely consistent or complete within OpenStreetMap, so some boundaries may not have this field set correctly (this mostly affects admin levels 3 & 4).

CartoCSS example:

#admin {
  [maritime=0] { line-color: black; }
  [maritime=1] { line-color: blue; }
}

#country_label_line

buffer: 2

This layer contains lines used as label leader lines for some country labels at low zoom levels. There are no data fields for this layer - only a single, simple line style is needed.

CartoCSS example:

#country_label_line { line-color: #333; }

#country_label

buffer: 256

This layer contains points used for labeling countries. The points are placed for minimal overlap with small to medium-sized text.

Names

See Name fields in the overview for information about names and translations.

Scalerank

The scalerank field is intended to help assign different label styles based on the size and available room to label different countries.

CartoCSS example:

#country_label {
  text-name: [name_en];
  text-face-name: 'Open Sans Semibold';
  text-size: 10;
  [scalerank=0] { text-size: 14; }
  [scalerank=1] { text-size: 13; }
  [scalerank=2] { text-size: 12; }
  [scalerank=3] { text-size: 11; }
}

#marine_label

buffer: 256

Points and lines for labeling major marine features such as oceans, seas, large lakes & bays.

Names

See Name fields in the overview for information about names and translations.

Labelrank & placement

The labelrank field is intended to help assign different label styles based on the size and available room to label different water bodies. The possible values are whole numbers 1 through 6.

The value of the placement field will be either point or line depending on the geometry type of the object.

CartoCSS example:

#marine_label {
  text-name: [name_en];
  text-face-name: 'Merriweather Italic';
  placement: point;
  [placement='line'] { placement: line; }
  text-size: 12;
  [labelrank=0] { text-size: 20; }
  [labelrank=1] { text-size: 18; }
  [labelrank=2] { text-size: 16; }
  [labelrank=3] { text-size: 15; }
  [labelrank=4] { text-size: 14; }
  [labelrank=5] { text-size: 13; }
}

#state_label

buffer: 256

Points for labeling states and provinces. Only a small number of countries are included.

Names

See Name fields in the overview for information about names and translations.

Area

The area field is the physical area of the entity in square kilometers. Use it to help filter and size your state labels at different zoom levels.

CartoCSS example:

#state_label {
  text-name: [name];
  text-face-name: 'Open Sans Regular';
  text-size: 12;
  [area>=10000] { text-size: 14; }
  [area>=500000] { text-size: 16; }
  [area>=1000000] { text-size: 18; }

#place_label

buffer: 128

This layer contains points for labeling human settlements.

Names

See Name fields in the overview for information about names and translations.

Types

The main field for styling labels for different kinds of places is type.

ValueDescription
citySettlement of about 100,000 or more people.
townUrban or rural settlement of about 10,000-100,000 people
villageUsually rural settlement of less than about 10,000
hamletRural settlement with a population of about 200 or fewer
suburbA distinct section of an urban settlement such as an annexed town, historical district, or large & important neighborhood.
neighbourhoodA named part of a larger settlement

Capitals

The capital field allows distinct styling of labels or icons for the capitals of countries, regions, or states & provinces.

capitallimited integer
2National capital
3Regional capital (uncommon)
4State / provincial capital

CartoCSS example:

#place_label {
  [capital=2] { marker-file: url("./icons/star-national.svg"); }
  [capital=3] { marker-file: url("./icons/star-region.svg"); }
  [capital=4] { marker-file: url("./icons/star-state.svg"); }
}

Scalerank

The scalerank field can be used to adjust the prominence of label styles for larger and more prominent cities. The value number from 0 through 9, where 0 is the large end of the scale (for example New York City). All places other than large cities will have a scalerank of null.

CartoCSS example:

#place_label[type='city] {
  text-name: [name];
  text-face-name: 'Open Sans Regular';
  text-size: 12;
  [scalerank>=0][scalerank<=2] { text-size: 18; }
  [scalerank>=3][scalerank<=4] { text-size: 16; }
  [scalerank>=5][scalerank<=6] { text-size: 14; }
  [scalerank>=7][scalerank<=8] { text-size: 13; }
}

Localrank

The localrank field can be used to adjust the label density by showing fewer labels. This method is preferred to CartoCSS's text-min-distance because it leads to far fewer labels clipped across tile boundaries. It is a whole number greater than 0 calculated by grouping places into a 128 pixel grid at each zoom level, then assigning each place a ranking within that grid. The most important place in that 128 pixels will get a localrank of 1, the second most important is 2, and so on. So to reduce the label density to 4 labels per tile, you can add the filter [localrank=1].

CartoCSS example:

#place_label[localrank<=1] {
  text-name: [name];
  text-face-name: 'Open Sans Regular';
}

Label direction

The ldir field can be used as a hint for label offset directions at lower zoom levels. For places with a scalerank value set, the ldir will be a cardinal direction such as N, E, SW.

CartoCSS example:

#place[type='city'] {
  text-name: [name];
  text-face-name: 'Open Sans Regular';
  text-placement-type: simple;
  text-dx: 3;
  text-dy: 3;
  [ldir='N'] { text-placements: 'N'; }
  [ldir='NE'] { text-placements: 'NE'; }
  [ldir='E'] { text-placements: 'E'; }
  [ldir='SE'] { text-placements: 'SE'; }
  [ldir='S'] { text-placements: 'S'; }
  [ldir='SW'] { text-placements: 'SW'; }
  [ldir='W'] { text-placements: 'W'; }
  [ldir='NW'] { text-placements: 'NW'; }
}

#water_label

buffer: 64

This layer contains points for labeling bodies of water such as lakes and ponds.

Names

See Name fields in the overview for information about names and translations.

Area

The area field holds the area of the associated water polygon in square meters (Mercator-projected units rounded to the nearest whole number, not real-world area). You can use it to adjust label size and visibility.

CartoCSS example:

#water_label {
  [zoom<=15][area>=200000],
  [zoom=16][area>=50000],
  [zoom=17][area>=10000],
  [zoom>=18][area>0] {
    text-name: [name];
    text-face-name: 'Open Sans Regular';
  }
}

#poi_label

buffer: 64

This layer is used to place icons and labels for various points of interest (POIs).

Names

See Name fields in the overview for information about names and translations.

Maki icons

The maki field is designed to make it easier to add icons to POIs using the Maki icon project, or with other icons that follow the same naming scheme.

CartoCSS example:

#poi_label[maki!=null] { marker-file: url("icons/[maki].svg"); }

Not all Maki icons are used, and different types of related POIs will sometimes have the same maki value (for example universities and colleges, or art supply shops and art galleries). The possible values for the maki field are listed below.

null
'airport'
'airfield'
'alcohol-shop'
'art-gallery'
'bakery'
'bank'
'bar'
'beer'
'bicycle'
'bus'
'cafe'
'car'
'campsite'
'cemetery'
'cinema'
'clothing-store'
'college'
'dog-park'
'embassy'
'entrance'
'fast-food'
'ferry'
'fire-station'
'fuel'
'garden'
'golf'
'grocery'
'harbor'
'heliport'
'hospital'
'laundry'
'library'
'lodging'
'monument'
'museum'
'music'
'park'
'pharmacy'
'camera'
'place-of-worship'
'rail'
'rail-light'
'rail-metro'
'religious-christian'
'religious-jewish'
'religious-muslim'
'police'
'post'
'prison'
'restaurant'
'school'
'shop'
'swimming'
'theatre'
'town-hall'
'suitcase'
'zoo'

Type

The type field contains a more specific classification intended for display - for example 'Cafe', 'Hotel', 'Laundry'. These values come from the original OpenStreetMap tags and are not a limited set.

Scalerank

The scalerank field is intended to help assign different label styles based on the prominence of different features.

ValueDescription
1The POI has a large area
2The POI has a medium-large area
3The POI has a small area, or is of a type that is commonly large and important (for example hospital, university)
4The POI has no known area

Controlling label density

The localrank field can be used to adjust the label density by showing fewer labels. This method is preferred to CartoCSS's text-min-distance because it leads to far fewer labels clipped across tile boundaries. It is a whole number >=1 calculated by grouping places into a ~300m projected grid, then assigning each place a ranking within that grid. The most important place in each cell will get a localrank of 1, the second most important is 2, and so on.

CartoCSS example:

#poi_label {
  [zoom=15][localrank<=1],
  [zoom=16][localrank<=2],
  [zoom=17][localrank<=4] { /* icon styles */ }
}

Rail station networks

The network field is aimed at helping assign icons for rail stations - the value will be null for all other types of POIs. They don't necessarily correspond to a specific network - for example u-bahn applies to any U-Bahn network in Germany. Some stations serve multiple networks; in these cases, multiple network names are joined with a dot (in alphabetical order).

ValueDescription
nullPOI is not a rail station
railDefault rail station
subwayDefault subway/metro station
lightDefault light rail station
dlrDocklands Light Rail, London, UK
dlr.london-overground.london-underground.national-railLondon, UK
dlr.london-undergroundLondon, UK
dlr.london-underground.national-railLondon, UK
dlr.national-railLondon, UK
london-overgroundLondon Overground, UK
london-overground.london-undergroundLondon, UK
london-overground.london-underground.national-railLondon, UK
london-overground.national-railLondon, UK
london-undergroundLondon Underground, UK
london-underground.national-railLondon, UK
national-railUK
washington-metroWashington DC Metro
wiener-linienVienna, Austria
metroParis Metro, France
rerParis regional commuter rail, France
metro.rerParis, France
transilienParis suburban rail, France
rer.transilienParis, France
moscow-metroMoscow Metro, Russia
s-bahnGermany
u-bahnGermany
s-bahn.u-bahnGermany

Additional information

The ref field is a short reference code that can be used as an alternative name. It is only used for airports.

#road_label

buffer: 64

Names

See Name fields in the overview for information about names and translations.

Route numbers

Besides the standard name fields, there is also a ref field that holds any reference codes or route numbers a road may have.

To aid with shield styling in TileMill and Mapnik, the reflen field conveys the number of characters present in the ref field. If the ref is 'I 95', then the reflen is 4.

CartoCSS example:

#road_label[reflen>=1] {
  shield-name: [ref];
  shield-face-name: 'Open Sans Regular';
  shield-file: url("./img/shield-[reflen].png");
}

Classes

The class field for road labels matches the #tunnel, #road, & #bridge layers.

ValueDescription
motorwayHigh-speed, grade-separated highways
mainTrunk, primary, secondary, and tertiary roads & links lumped together for simpler styling.
streetStandard unclassified or residential streets
street_limitedStreets that may have limited or no access for motor vehicles. Pedestrian streets, roads under construction, private roads, etc.
serviceAccess roads, alleys, agricultural tracks, and other services roads.
pathFoot paths, cycle paths, ski trails.
aerialwaySki lifts, gondolas, and other types of aerialway.
golfThe approximate centerline of a golf course hole

Additional information

The len field stores the length of the road segment in projected meters, rounded to the nearest whole number. This can be useful for limiting some label styles to longer roads.

#waterway_label

buffer: 64

This layer contains line geometries that match those in the #waterway layer but with name fields for label rendering.

Label text

See Name fields in the overview for information about names and translations.

Classes & types

The class and type fields match those in the #waterway layer.

ValueDescription
riverEverything from the Amazon down to small creeks a couple meters wide
canalMedium to large artificial waterway
streamVery small waterway, usually no wider than a meter or two
stream_intermittentClass only. A stream that does not always have water flowing through it.
drainMedium to small artificial channel for rainwater drainage, often concrete lined.
ditchSmall artificial channel dug in the ground for rainwater drainage.

#housenum_label

buffer: 64

This layer contains points used to label the street number parts of specific addresses.

The house_num field contains house and building numbers. These are commonly integers but may include letters or be only letters, for example "1600", "31B", "D". If an address has no number tag but has a house name or building name, the house_num field will be the name instead.

CartoCSS example:

#housenum_label {
  text-name: [house_num];
  text-face-name: 'Open Sans Regular';
}

Changelog

A summary of the changes from v4:

  • New class field added in the #waterway layer. You can safely ignore this change when upgrading styles from v4
  • New maki values in the #poi_label layer: bakery, camera, car, clothing-store, dog-park, entrance, laundry, rail-light, rail-metro, suitcase. If upgrading a v4 style that uses [maki] in a URL expression (for example marker-file), you will need to make sure to add files to match the new values.
  • New network values in the #poi_label layer: wiener-linien, metro, rer, metro.rer, transilien, rer.transilien, moscow-metro, s-bahn, u-bahn, sbahn.u-bahn. If upgrading a v4 style that uses [network] in a URL expression (for example marker-file), you will need to make sure to add files to match the new values.
  • New #housenum_label layer for labeling house and building numbers. You can safely ignore this change when upgrading styles from v4
  • New localrank field in the #place_label layer. When upgrading styles from v4 it is recommended to remove any text-min-distance styles from you place labels and use localrank to control label density.
  • New class values in the #landuse layer: agriculture, glacier, grass, piste, rock, scrub. When upgrading styles from v4, look for catch-all styles that may have unexpected results for unhandled values (for example dark gray polygon fills, black outlines).
  • In the #road_label layer, the ref field is now available for all road types. Before it was only available for motorways. For most style upgrades from it should be safe to ignore this change, though there may be edge cases where action is needed.
  • The #marine_label layer now contains actual point geometries so you can use ['mapnik::geometry_type'=1] instead of [placement='point']. The tileset keeps placement for backwards-compatibility, but no action is necessary for this change when upgrading styles from v4.
  • New capital field added in the #place_label layer to identify cities that are the capitals of countries, regions, or states/provinces. You can safely ignore this change when upgrading styles from v4.