Mapbox Streets v8

Source ID:
mapbox.mapbox-streets-v8
Note: Mapbox Streets v8 is currently a beta release. The data structure is stable as documented, but there are still known issues and limited style examples.

This is an in-depth guide to the data inside the Mapbox Streets vector tile source to help with styling.

Overview

Data sources & updates

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 OSM data structure and tagging system is not neccessary 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.

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 Mapbox data
water (ocean parts)OpenStreetMapData.com
place_label, types ‘country’ & ‘state’custom Mapbox data
natural_label, types ‘ocean’ & ‘sea’ custom Mapbox data

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:

  1. Point
  2. Linestring / multilinestring
  3. Polygon / multipolygon

In Mapbox Studio, you can select just one or two or all of the 3 types with the Geometry Type toggles in each layer’s data selection tab.

OSM IDs

OSM IDs are not stored as object properties but as object IDs within the vector tile. This means they are not available for styling via Mapbox Studio, but can still be interacted with via Mapbox GL JS and other vector tile libraries.

OpenStreetMap ID spaces are not unique across node, way, and relation object types. In order to make them unique for vector tiles, the IDs are transformed based on their OpenStreetMap object type.

OSM typeOSM ID transform
node id × 10 eg. 123 → 1230
way (id × 10) + 1 eg. 123 → 1231
relation(id × 10) + 4 eg. 123 → 1234

In many cases, mulitple objects from OpenStreetMap will be combined into a single object in our vector tiles. For example, water polygons are unioned to avoid seams and road lines are joined to save space and simplify better. In these cases the osm_id will either be 0, or one of the input IDs chosen at random.

Changelog

The layers and properties in Mapbox Streets v8 have undergone a major reorganization to optimize for styling with the latest features in Mapbox Studio such as expressions. We’ve also expanded coverage of feature types and properties for styling, with a particular emphasis on labels & icons.

  • 3 new layer names:
  • 9 removed layer names - the data from these layers have moved into other layers as noted here:
  • New ranking fields fields for label layers:
  • Name fields:
    • Translated name fields (name_en, name_fr, etc) will now contain null values where no translation is available, rather than falling back to name. This will allow you to customize your fallback preferences using Mapbox GL expressions.
    • name_zh field removed and replaced by name_zh-Hant (traditional Chinese)
    • New field: name_script indicates the primary script used in the name field (Latin, Cyrillic, etc)
  • admin layer:
    • Data source has changed to match Mapbox Enterprise Boundaries
    • New field: worldview - provides the option to cater boundary lines to different locales. See boundaries section below for details.
    • The admin_level now has a range of 0 through 2 with slightly different division definitions compared to v7 - see boundaries section below for details.
    • The disputed and maritime fields now have text values of true or false rather than numeric 1 and 0
  • aeroway layer:
    • New field: ref indicates the runway or taxiway identifier
  • place_label layer:
    • New fields:
      • iso_3166_1: indicates the 2-letter country/territory code of the place or the country that the place is within.
      • symbolrank and filterrank: see description in table
      • text_anchor - replaces ldir
    • Added support for OSM place=quarter
    • Several feature types have moved to either poi_label or natural_label
  • poi_label layer:
    • New fields:
      • category_en / category_zh-Hans: contains POI category description for text display in English / simplified Chinese
      • class: contains broad categories useful for filtering & symbol styling
      • filterrank: see description in table
    • Many new maki values
    • Many new feature types added
  • road layer:
    • New fields:
      • Fields from former road_label layer: names, ref, reflen, len, shield, iso_3166_2
      • toll: true for toll roads and not present / null for all other roads.
      • surface: indicates either paved or unpaved where this data is available from OSM.
      • bike_lane: indicates presence and location of a bike lane that is part of the road itself (as opposed to a separated bike lane).
    • New class values:
      • service_rail - includes service tracks such as sidings or yard rails. These were previously included in the minor_rail class.
      • link has been removed and broken out into trunk_link, primary_link, secondary_link, tertiary_link
    • Previous road_label layer is now merged into road layer, with all label fields included: len, ref, reflen, and shield.
  • transit_stop_label layer:
    • Replaces the railway_station_label layer from v7 and includes some new features such as bus stops (new), ferry terminals, and bikeshare stations (previously in the poi_label layer).
    • New fields:
      • mode: provides more detail about the particular mode of transport served by a stop/station
      • stop_type: value is one of: stop, station, entrance

Data stability

As we make ongoing data updates to reflect changes in the world, we may also add new layers, fields, and values Mapbox Streets v8 tiles. Our goal is to do this in a way that preserves compatibility with existing v8 styles as much as possible. Here’s what you need to know about how Mapbox Streets v8 may change in the future:

  • Layers
    • Existing layers will not be renamed or removed
    • New layers may be added
  • Fields
    • Existing fields will not be renamed or removed
    • New fields may be added to any layer
  • Field values
    • The meanings of existing values will not change
    • Values of specific features may change to correct errors or reflect real-world changes.
    • New values may be added to any field unless otherwise noted in this documentation
    • Fields that may contain null values are noted in this documentation, and null values will not be introduced to existing layers that do not already have them.

You should design your styles to account for the possibility of new field values. Be explicit in your filters where possible, and make sure to include appropriate default styles when using expressions.

Common fields

name text & name_<lang-code> text

Label names are available in a number of languages. The name_* value will be null if no translation data is available for a given feature; when styling label layers, you are responsible for determining an appropriate fallback approach.

If the name field is null for a particular feature, then all of the language-specific name_* fields will also be null. This means that name should always be the final fallback value if you want to include it in your set of label languages.

FieldDescription
nameThe name (or names) used locally for the place.
name_arArabic
name_enEnglish
name_esSpanish
name_frFrench
name_deGerman
name_ptPortuguese
name_ruRussian
name_zh-HansSimplified Chinese
name_zh-HantTraditional Chinese (if available, but may contain some Simplified Chinese)
name_jaJapanese
name_koKorean

For languages that may have regional variations, no particular preference is given where place name spellings differ.

name_script text

Wherever there is a name field, there is also a name_script field that describes the primary script used in that text. This can be helpful for customizing fonts or language fallback conditions. Values include:

Arabic Armenian Bengali Bopomofo Canadian_Aboriginal Common Cyrillic Devanagari Ethiopic Georgian Glagolitic Greek Gujarati Gurmukhi Han Hangul Hebrew Hiragana Kannada Katakana Khmer Lao Latin Malayalam Mongolian Myanmar Nko Sinhala Syriac Tamil Telugu Thaana Thai Tibetan Tifinagh Unknown

The value will be null if name is also null.

sizerank number

The sizerank field is included in label layers where points or lines have been derived from polygons, such as poi_label, natural_label, airport_label. It lets you style & filter based on the size of a feature relative to the current zoom level. The largest objects are given sizerank=0, and points are given sizerank=16.

A single feature will have a changing sizerank as you zoom in and the relative size of the feature increases. For example, a park might have a sizerank of 9 at z11, 6 at z12, and 2 at z13.

The value will never be null and will always be within the range 0-16.

filterrank number

Filterrank is a value from 0-5 used to customize label density. It’s intended to be used in style layer filters (in the ‘Select data’ tab in Mapbox Studio). The value is relative to the current zoom level. For example the same POI might have filterrank=5 at z10 while having filterrank=1 at z14, since zooming in changed the relative importance of the POI.

You could set filterrank<=1 to only show the most prominent labels, filterrank<=3 to produce moderate density, and filterrank<=5 to see as many labels as possible.

The value will never be null and will always be in the range of 0-5.

maki text

Some layers have a maki field designed to make it easy to assign icons using the Maki icon project, or with other icons that follow the same naming scheme. Each layer uses a different subset of the names, but the full list of values used in Mapbox Streets is compiled here so you can ensure your style has all the icons needed across different layers.

Not all icons from the Maki project are used in Mapbox Streets, and different types of related features will sometimes have the same maki value (eg universities and colleges, or art supply shops and art galleries). Nameless POIs will have never have a maki value of marker (the generic default).

The possible values for the maki field for all layers are listed below. Icon names that were not part of any layer in v7 are marked with 🆕. No further values will be added in Mapbox Streets v8.

airport_label:

airport airfield heliport rocket

natural_label:

marker mountain volcano waterfall 🆕

poi_label:

alcohol-shop american-football 🆕 amusement-park aquarium art-gallery attraction bakery bank bar basketball 🆕 beach 🆕 beer bicycle bowling-alley 🆕 bridge 🆕 cafe campsite car car-rental 🆕 car-repair 🆕 casino 🆕 castle cemetery charging-station 🆕 cinema clothing-store college communications-tower 🆕 confectionery 🆕 convenience 🆕 dentist doctor dog-park drinking-water embassy farm 🆕 fast-food fire-station fitness-centre 🆕 fuel furniture 🆕 garden globe 🆕 golf grocery harbor hardware 🆕 horse-riding 🆕 hospital ice-cream information jewelry-store 🆕 laundry library lodging marker mobile-phone 🆕 monument museum music optician 🆕 park parking 🆕 parking-garage 🆕 pharmacy picnic-site pitch 🆕 place-of-worship playground police post prison ranger-station 🆕 religious-buddhist 🆕 religious-christian religious-jewish religious-muslim restaurant restaurant-noodle 🆕 restaurant-pizza 🆕 restaurant-seafood 🆕 school shoe 🆕 shop skateboard 🆕 slipway 🆕 stadium suitcase 🆕 swimming table-tennis 🆕 tennis 🆕 theatre toilet town-hall veterinary viewpoint 🆕 volleyball 🆕 watch 🆕 watermill 🆕 windmill 🆕 zoo

transit_stop_label:

bicycle-share bus ferry rail rail-metro rail-light entrance

Layer Reference

admin
buffer: 4

This layer contains boundary lines for national and subnational administrative units. The data source & shapes match polygons from the Mapbox Enterprise Boundaries product.

admin_level number

The admin_level field separates different levels of boundaries.

ValueDescription
0Countries
1First-level administrative divisions
2Second-level administrative divisions

worldview text

Mapbox Streets v8 introduces the notion of worldviews to the administrative boundary layer. The vector tiles contain multiple versions of some boundaries, each with a worldview value indicating the intended audience. It is important to apply a worldview filter to all of your admin style layers, otherwise your map will show conflicting & overlapping boundary lines. The filter should always include both all and one of the region-specific values.

ValueDescription
allAppropriate for all worldviews (most boundaries)
CNBoundaries for a mainland Chinese audience/worldview, but not officially approved for use in the PRC.
INBoundaries conforming to cartographic requirements for use in India
USBoundaries for an American audience, & which are generally appropriate outside of China & India. Lines do not necessarily reflect official US foreign policy.

disputed text

Boundary lines with a disputed value of true should have a dashed or otherwise distinct style applied in styles. No single map of the world will ever keep everybody happy, but acknowledging disputes where they exist is an important aspect of good cartography. The value will always be either true or false (never null).

maritime text

Mapbox Streets v8 includes a minimal set of maritime boundaries. These have a maritime value of true to use for distinct styling or filtering. The value will always be either true or false (never null).

iso_3166_1 text

The iso_3166_1 field contains the ISO 3166-1 alpha-2 code or codes that apply to a boundary. For subnational boundaries this will be a single code of the parent country. For international boundaries between two countries, the value will be the codes of both countries in alphabetical order, separated by a dash (-).

aeroway
buffer: 4

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

type text

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

ref text

The ref field contains runway and taxiway identifiers. The value may be null.

airport_label
buffer: 64

This layer contains point geometries that are one of: airport, airfield, heliport, and rocket.

See names and name_script in for information about names and translations available for label text.

See sizerank for information about that field.

ref text

The ref field contains short identifier codes for many airports. These are pulled from the OpenStreetMap tags iata, ref, icao, or faa (in order of preference). The value may be null.

maki text

The maki field lets you assign different icons to different types of airports. See the `maki part of the Common Fields section for more details.

ValueDescription
airportMost commercial airports
airfieldSmaller airports & private airfields
heliportFor helicopters
rocketSpaceflight facilities

building
buffer: 2

Large buildings appear at zoom level 13, and all buildings are included in zoom level 14 and up.

underground text

The underground field will be true for buildings that are underground (for example, some subway stations). This value will always be either true or false (never null).

type text

The type field lets you differentiate building parts from building outlines. Building part polygons intended primarily for 3D rendering have a value of building:part. Building outlines (covering the full footprint of a building) will have a value of building if tagged as building=yes on OpenStreetMap, otherwise the value will match the building tag from OpenStreetMap (see TagInfo for common values).

height number

The height field contains the height of a building or building part in meters (rounded to the nearest integer). In many cases this value is derived from the building:levels tag on OpenStreetMap - we estimate 3 meters per level if no exact height is specified. This value may be null where extrude is false.

min_height number

The min_height field contains the height in meters from the ground to the bottom of a building part, for cases where the bottom of the part is not on the ground. This allows for proper extrusion rendering of things such as sky bridges and cantilevered building parts. This value may be null where extrude is false.

extrude text

The extrude field indicates whether the object should be included in 3D-extrusion renderings. For example a complex building might have various building:part objects mapped with different heights, in addition to a building object representing the footprint of the entire building. Only the building:part objects are needed for 3D rendering, so the full footprint outline will have an extrude value of false. The extrude value will always be either true or false (never null).

housenum_label
buffer: 64

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

house_num text

The house_num field countains house and building numbers. These are commonly integers but may include letters or be only letters, eg “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.

landuse_overlay
buffer: 8

This layer is for landuse / landcover polygons that should be drawn above the #water layer.

class text

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

ValueDescription
national_parkRelatively large area of land set aside by a government for human recreation and environmental protection
wetlandWetlands that may include vegetation (marsh, swamp, bog)
wetland_novegWetlands that probably dont contain vegetation (mud, tidal flat)

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 ensure 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.

class text

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

ValueDescription
aboriginal_landsThe boundary of aboriginal lands.
agricultureVarious types of crop and farmland
airportAirport grounds
cemeteryCemeteries and graveyards
glacierGlaciers or permanent ice/snow
grassGrasslands, meadows, fields, lawns, etc
hospitalHospital grounds
parkCity parks, village greens, playgrounds, national parks, nature reserves, etc
pisteArea used for skiing, snowboading, and other snow/mountain sports
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

motorway_junction
buffer: 8

This layer contains point geometries for labeling motorway junctions (aka highway exits). Classes and types match the types in the road layer.

ref text, reflen number, & name text

The motorway junction layer has a ref field and a name field for styling labels. The reflen field tells you how long the ref value is in case you want to style this layer with shields. All of these fields may be null.

class text & type text

The class and type fields tell you what kind of road the junction is on. See the #road layer for possible values.

natural_label
buffer: 64

The natural_label layer contains points and lines for styling natural features such as bodies of water, mountain peaks, valleys, deserts, and so on.

See names and name_script in for information about names and translations available for label text.

See sizerank for information about that field.

class text & maki text

The natural_label layer is organized into a number of different classes for styling & filtering. Within each class, serveral maki values are available for assigning icons to features - see the maki part of the Common Fields section for more details about that field.

classmaki valuesfeature types
baymarkerinlet in a large body of water
canalmarker
dockmarkerenclosed area of water for ships
glaciermarkerglacier
landformmountain, volcano, markerpeaks, meadows, cave entrances, archipelago, island, islet, saddle, fell, desert, valley, etc.
oceanmarkeroceans
reservoirmarkerhuman water containment areas
rivermarker
seamarkerseas and other very large water features including some gulfs, straits, bays, etc.
streammarker
water_featurewaterfall, markerwaterfalls
watermarkerlakes, ponds, etc.
wetlandmarkerwetland, marsh

elevation_m number & elevation_ft number

The elevation_m and elevation_ft fields hold the feature elevation in meters and feet, respectively. Values are rounded to the nearest whole number and do not include units. Use a text field such as {elevation_ft} feet or {elevation_m}m in Mapbox Studio to display the units. These fields may be null.

place_label
buffer: 128

This layer contains points for labeling places including countries, states, cities, towns, and neighbourhoods.

See names and name_script in for information about names and translations available for label text.

See filterrank for information on using that field.

type

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

ValueDescription
countrySovereign or partially-recognized states
sarSpecial Administrative Region
territorySemi-autonomous or other subnational entities with ISO 3166-1 codes
disputed_territoryDisputed territories with ISO 3166-1 codes.
stateFirst-level administrative divisions or similar. Only a small subset of these are included in order to reduce clutter and put focus on cities, towns, etc.
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.
quarterA large neighborhood or section of a larger city or town
neighbourhoodA smaller neighborhood or part of a larger settlement

symbolrank

The symbolrank value is intended to simplify styling of the label size and symbol prominence of place features. It ranges from 1 to 19 and is consistently assigned across zoom levels - ie a place with a symbolrank of 6 at z4 will have the same value as you zoom in to any other level.

The value will never be null and will always be in the range of 1-19.

iso_3166_1 text

The iso_3166_1 field contains the ISO 3166-1 alpha-2 code of the country the place is in. The value may be null - either due to location match errors or for features that are in international waters.

capital number

The capital field allows distinct styling of labels or icons for the capitals of countries, regions, or states & provinces. The value of this field may be 2, 3, 4, 5, or 6. National capitals are 2, and 3 through 6 represent capitals of various sub-national administrative entities. These levels come from OpenStreetMap and have different meanings in different countries - see the OpenStreetMap wiki for specific details.

The value will be null for any place that is not a capital.

text_anchor text

The text_anchor field can be used as a hint for label placement. Possible values match the Mapbox GL Style Spec for text anchor. The value may be null.

ValueMeaning
centerThe center of the text is placed closest to the anchor.
leftThe left side of the text is placed closest to the anchor.
rightThe right side of the text is placed closest to the anchor.
topThe top of the text is placed closest to the anchor.
bottomThe bottom of the text is placed closest to the anchor.
top-leftThe top left corner of the text is placed closest to the anchor.
top-rightThe top right corner of the text is placed closest to the anchor.
bottom-leftThe bottom left corner of the text is placed closest to the anchor.
bottom-rightThe bottom right corner of the text is placed closest to the anchor.

poi_label
buffer: 64

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

See names and name_script in for information about names and translations available for label text.

See sizerank and filterrank for information on using those fields to style text size and label density.

See maki for more information about using this field for assigning icons.

class text

The class field groups points of interest into broad categories for styling purposes. The values are useful for designing icon color schemes, for example.

arts_and_entertainment building commercial_services education food_and_drink food_and_drink_stores general historic industrial landmark lodging medical motorist park_like place_like public_facilities religion sport_and_leisure store_like visitor_amenities

type text

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

category_en text & category_zh-Hans text

The category_en & category_zh-Hans fields contain translated category descriptions for POIs. These can be used as a fallback or as supplemental information where English or simplified Chinese translations may not exist. These values may be null.

Language coverage may be expanded in a future v8 update.

road
buffer: 4

The roads layer contains lines, points, and polygons needed for drawing features such as roads, railways, paths and their labels.

See names and name_script in for information about names and translations available for label text.

class text

The main field used for styling the road layers is class.

ValueDescription
motorwayHigh-speed, grade-separated highways
motorway_linkLink roads/lanes/ramps connecting to motorways
trunkImportant roads that are not motorways.
trunk_linkLink roads/lanes/ramps connecting to trunk roads
primaryA major highway linking large towns.
primary_linkLink roads/lanes connecting to primary roads
secondaryA highway linking large towns.
secondary_linkLink roads/lanes connecting to secondary roads
tertiaryA road linking small settlements, or the local centres of a large town or city.
tertiary_linkLink roads/lanes connecting to tertiary roads
streetStandard unclassified, residential, road, and living_street road types
street_limitedStreets that may have limited or no access for motor vehicles.
pedestrianIncludes pedestrian streets, plazas, and public transportation platforms.
constructionIncludes motor roads under construction (but not service roads, paths, etc).
trackRoads mostly for agricultural and forestry use etc.
serviceAccess roads, alleys, agricultural tracks, and other services roads. Also includes parking lot aisles, public & private driveways.
ferryThose that serves automobiles and no or unspecified automobile service.
pathFoot paths, cycle paths, ski trails.
major_railRailways, including mainline, commuter rail, and rapid transit.
minor_railIncludes light rail & tram lines.
service_railYard and service railways.
aerialwaySki lifts, gondolas, and other types of aerialway.
golfThe approximate centerline of a golf course hole
roundaboutCircular continous-flow intersection
mini_roundaboutSmaller variation of a roundabout with no center island or obstacle
turning_circle(point) Widened section at the end of a cull-de-sac for turning around a vehicle
turning_loop(point) Similar to a turning circle but with an island or other obstruction at the centerpoint
traffic_signals(point) Lights or other signal controlling traffic flow at an intersection

oneway text

The 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. The value will always be either true or false (never null).

structure text

The structure field describes whether the road segment is a bridge, tunnel, ford, or none of those. No further values will be added in Mapbox Streets v8.

iso_3166_2 text

The ISO 3166-2 code of the state/province/region the road is in. Not all areas are covered by this standard and the value may be null.

ref text & reflen number

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

The reflen value indicates how many characters are in the corresponding ref to help choose an appropriate size of shield graphic. The overall valid range is 2-6 but more detailed ranges for specific shield designs are noted below. Note that ref values with a single character are assigned a reflen value of 2 to reduce the number of required shield graphics.

From zoom levels 6 through 10, ref values are attached to separate points rather than lines in order to optimize symbol placement.

Both ref & reflen may be null.

shield text

The shield values help to assign highway shield graphics. They should be combined with ref for the text on the shield and reflen to determine the width of shield image needed.

Routes that can be symbolized with shields of a common shape & color have generic shared shield values:

Valuereflen rangeDescription
default2-6No specific shield design suggested.
rectangle-white2-6
rectangle-red2-6
rectangle-orange2-6
rectangle-yellow2-6
rectangle-green2-6
rectangle-blue2-6
circle-white2-6

Other highways with more specific shield design requirements are captured individually:

Valuereflen rangeDescription
ae-national3-4United Arab Emirates national routes
ae-d-route3-4UAE Dubai D-routes
ae-f-route3UAE Fujairah F-routes
ae-s-route4UAE Sharjah S-routes
au-national-highway2-3Australia national highways
au-national-route2-6Australia national routes
au-state2-6Australia state roads
au-tourist2-3Australia tourist routes
br-federal3Brazil federal highways
br-state2-3Brazil state highways
ch-motorway2-3Switzerland motorways
cn-nths-expy3-5China national expressway
cn-provincial-expy3-5China provincial/regional expressway
de-motorway2-3Germany motorways (Autobahnen)
gr-motorway2-4Greece motorways
hk-strategic-route2Hong Kong strategic routes
hr-motorway3-4Croatia motorways
hu-motorway2-3Hungary motorways
hu-main2-5Hungary main roads
in-national2-4India national highways & expressways
in-state2-3India state highways
kr-natl-expy2-3South Korea national expressways
kr-natl-hwy2South Korea national highways
kr-metro-expy2-3South Korea metropolitan expressways
kr-metropolitan2-6South Korea metropolitan routes
kr-local2-6South Korea local routes
mx-federal2-4Mexico federal highways
mx-state2-4Mexico state highways
nz-state2-3New Zealand state highways
pe-national2-3Peru national highways
pe-regional3-4Peru departmental / regional highways
ro-national2-3Romania national roads
ro-county3-4Romania county roads
ro-communal2-4Romania communal roads
si-motorway2Slovenia motorways
tw-national2Taiwan national routes
tw-provincial-expy2Taiwan provincial expressways
tw-provincial2Taiwan provincial routes
tw-county-township2-6Taiwan county / township routes
us-interstate2-4US Interstates
us-interstate-duplex4-5US Interstates - segment shared by 2 route numbers
us-interstate-business2-3US Interstates - business routes
us-interstate-truck2-3US Interstates - truck routes
us-highway2-4US highways
us-highway-duplex3-5US highways - segment shared by 2 route numbers
us-highway-alternate2-3US highways - alternate routes
us-highway-business2-3US highways - business routes
us-highway-bypass2-3US highways - bypasses
us-highway-truck2-3US highways - truck routes
us-bia2-4US BIA Indian routes
za-national2-3South Africa national routes
za-provincial2South Africa provincial routes

The shield value will be null where ref is also null. No further shield values will be added in Mapbox Streets v8.

type text

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. Several classes pull in additional detail when it is available from OpenStreetMap.

Possible construction class type values:

construction:motorway construction:motorway_link construction:trunk construction:trunk_link construction:primary construction:primary_link construction:secondary construction:secondary_link construction:tertiary construction:tertiary_link construction:unclassifed construction:residential construction:road construction:living_street construction:pedestrian construction

Possible track class type values:

track:grade1 track:grade2 track:grade3 track:grade4 track:grade5 track

Possible service class type values:

service:alley service:emergency_access service:drive_through service:driveway service:parking service:parking_aisle service

For the path class, some custom type assignments have been made based on insight from various categorical, physical, and access tags from OpenStreetMap.

ValueDescription
stepsaka stairs
corridorAn indoors passageway
sidewalkaka pavement in many places outside North America
crossingUsually connects sidewalk lines across a road
pisteSki & snowboard trails, both downhill and cross-country.
mountain_bikeTrails used primarily or exclusively for mountain biking
hikingHiking trails or otherwise rough pedestrian paths
trailMay be suitable for either hiking or mountain biking
cyclewayPaths primarily or exclusively for cyclists
footwayPaths primarily or exclusively for pedestrians
pathUnspecified or mixed-use paths
bridlewayEquestrian trails

Possible ferry class type values:

ValueDescription
ferry_autoFerry serves automobiles
ferryNo or unspecified automobile service

Possible aerialway class type values:

ValueDescription
aerialway:cablecarJust one or two large cars. The cable forms a loop, but the cars do not loop around, they just move up and down on their own side.
aerialway:gondolaMany cars on a looped cable.
aerialway:mixed_liftMix of chair lifts and gondolas on the same line; may change seasonally.
aerialway:chair_liftLooped cable with a series of single chairs and exposed to the open air.
aerialway:drag_liftIncludes t-bars, j-bars, platter/button lifts, and tow ropes
aerialway:magic_carpetConveyor belt installed at the level of the snow, some include a canopy or tunnel.
aerialwayOther or unspecified type of aerialway

layer number

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

len number

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. The value may be null where the geometry is not a line.

structure
buffer: 4

This layer includes lines and polygons for structures which are not buildings. This includes both natural and human features - cliffs, walls, piers, gates.

Cliff data 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.

class text

ValueDescription
cliffThe precipice of a vertical or very steep drop, gullies are included
fenceInclude various types of fence and wall barriers
gateOnly gates that are lines or areas are included
hedgeA line of closely spaced shrubs and tree species, which form a barrier or mark the boundary of an area
landIncludes breakwaters and piers

type text

The type field contains the original value of the feature’s primary tag from OSM.

transit_stop_label
buffer: 64

The transit_stop_label contains points for symbolizing transit stops, stations, and associated features such as entrances.

See names and name_script in for information about names and translations available for label text.

stop_type text

ValueDescription
stationUsed as the standard stop type for most rail & ferry modes. For buses and trams, stations represent centralized hubs.
stopUsed for bus and tram modes as the standard stop type. They are generally more frequently-spaced than stations and may need smaller symbols/text.
entranceSpecific entry points to a station

mode text

ValueDescription
railNational, regional, or commuter rail systems.
metro_railUrban rapid transit systems with dedicated rights of way, sometimes partially or fully underground.
light_railLess capacity than heavy/metro rail. Often on tracks separated from motor traffic but may share grade at intersections.
tramLighter rail with 1 or 2 carriages, often on a tracks shared with motor vehicle traffic.
monorailOften medium-low capacity and with localized or private use such as in theme parks or airports.
funicularCable-driven inclined railways. Often touristic and low-capacity.
bicycleFor bicycle rental docks/stations
busFor bus stops or stations
ferryA boat that may take passengers on foot, in motor vehicles, or both

maki text

The maki field lets you assign icons to the rail station based on a few basic station types. See maki in the Common Fields section for more information.

ValueDescription
bicycle-share
bus
ferry
railDefault rail station
rail-metroStation for a subway, metro, or other rapid-transit system
rail-lightLight rail station
entranceSpecific station entrance points (eg stairs, escalators, elevators)

network text

The network field lets you assign more specific icons for rail stations that are part of specific local or regional transit systems. They don’t necessarily correspond to a specific network - eg de-u-bahn applies to any U-Bahn network in Germany since these can all use the same icon in a map style. Some stations serve multiple networks; in these cases, multiple network names are joined with a dot (in alphabetical order).

If none of the specific networks below apply to a station, the network value will be the same as the maki value (see previous section).

ValueDescription
barcelona-metroBarcelona, Spain
boston-tBoston, Massachusetts
chongqing-rail-transitChongqing, China
de-s-bahnGermany
de-s-bahn.de-u-bahnGermany
de-u-bahnGermany
delhi-metroDelhi, India
gb-national-railLondon, United Kingdom
gb-national-rail.london-dlrLondon, United Kingdom
gb-national-rail.london-dlr.london-overground.london-tfl-rail.london-undergroundLondon, United Kingdom
gb-national-rail.london-dlr.london-overground.london-undergroundLondon, United Kingdom
gb-national-rail.london-dlr.london-undergroundLondon, United Kingdom
gb-national-rail.london-overgroundLondon, United Kingdom
gb-national-rail.london-overground.london-tfl-rail.london-undergroundLondon, United Kingdom
gb-national-rail.london-overground.london-undergroundLondon, United Kingdom
gb-national-rail.london-tfl-railLondon, United Kingdom
gb-national-rail.london-tfl-rail.london-overgroundLondon, United Kingdom
gb-national-rail.london-tfl-rail.london-undergroundLondon, United Kingdom
gb-national-rail.london-undergroundLondon, United Kingdom
hong-kong-mtrHong Kong
kiev-metroKiev, Ukraine
london-dlrDocklands Light Rail, London, United Kingdom
london-dlr.london-tfl-railLondon, United Kingdom
london-dlr.london-tfl-rail.london-undergroundLondon, United Kingdom
london-dlr.london-undergroundLondon, United Kingdom
london-overgroundLondon Overground, United Kingdom
london-overground.london-tfl-railLondon Overground, United Kingdom
london-overground.london-tfl-rail.london-undergroundLondon Overground, United Kingdom
london-overground.london-undergroundLondon, United Kingdom
london-tfl-railLondon, United Kingdom
london-tfl-rail.london-undergroundLondon, United Kingdom
london-undergroundLondon Underground, United Kingdom
madrid-metroMadrid, Spain
mexico-city-metroMexico City, Mexico
milan-metroMilan, Italy
moscow-metroMoscow Metro, Russia
new-york-subwayNew York City, New York
osaka-subwayOsaka, Japan
oslo-metroOslo, Norway
paris-metroParis Metro, France
paris-rerParis regional commuter rail, France
paris-metro.paris-rerParis, France
paris-rer.paris-transilienParis, France
paris-transilienParis suburban rail, France
philadelphia-septaPhiladelphia, Pennsylvania
san-francisco-bartSan Francisco, California
singapore-mrtSingapore
stockholm-metrostockholm, Sweden
taipei-metroTaipei, Taiwan
tokyo-metroTokyo, Japan
vienna-u-bahnVienna, Austria
washington-metroWashington DC Metro

No further network values will be added in Mapbox Streets v8.

water
buffer: 8

This is a simple polygon layer with no differentiating types or classes. Water bodies are filtered and simplified according to scale - only oceans and very large lakes are shown at the lowest zoom levels, while smaller and smaller lakes and ponds appear as you zoom in.

waterway
buffer: 4

The waterway layer contains classes for rivers, streams, canals, etc represented as lines. These classes can represent a wide variety of possible widths. It’s best to have your line stying biased toward the smaller end of the scales since larger rivers and canals are usually also represented by polygons in the #water layer. Also works best under #water layer.

class text & type text

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.