Mapbox Streets v8
This tileset reference document includes information to help you use the data in the Mapbox Streets v8 tileset.
Overview
Mapbox Streets v8 is a Mapbox-provided vector tileset that includes geometries and metadata for roadways, terrain, administrative boundaries, building footprints, land use classifications, rail stations, points of interest, and more.
For full examples of using Mapbox Streets vector tiles to create a map style, see the default styles in Mapbox Studio.
Data sources and updates
Mapbox Streets v8 vector tiles are based on a combination of proprietary Mapbox data, Open Data projects such as OpenStreetMap, Microsoft Open Maps and Wikidata, as well as data vendors such as Zenrin in Japan.
Layer | Data sources |
---|---|
admin | Globally: Proprietary Mapbox data |
aeroway | Globally: OpenStreetMap replication feed Japan: OpenStreetMap replication feed, Zenrin |
airport_label | Globally: OpenStreetMap replication feed Japan: OpenStreetMap replication feed, Zenrin |
building | Globally: Proprietary Mapbox data, OpenStreetMap, Microsoft Japan: Zenrin |
housenum_label | Globally: OpenStreetMap replication feed Japan: Zenrin |
landuse_overlay | Globally: OpenStreetMap replication feed Japan: Zenrin |
landuse | Globally: OpenStreetMap replication feed Japan: Zenrin |
motorway_junction | Globally: OpenStreetMap replication feed Japan: Zenrin |
natural_label , types ocean and sea | Globally: Proprietary Mapbox data |
natural_label , all other types | Globally: OpenStreetMap replication feed Japan: Zenrin |
place_label , types country and state | Globally: Proprietary Mapbox data |
poi_label | Globally: OpenStreetMap replication feed Japan: Zenrin |
road | Globally: OpenStreetMap replication feed Japan: Zenrin |
structure | Globally: OpenStreetMap replication feed Japan: Zenrin |
transit_stop_label | Globally: OpenStreetMap replication feed Japan: Zenrin |
water (ocean parts) | Globally: OpenStreetMap Japan: Zenrin |
waterway | Globally: OpenStreetMap replication feed Japan: Zenrin |
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.
Data quality
Besides the daily efforts of contributors all over the globe, the OpenStreetMap community uses several other methods for identifying errors in the data, including multiple quality-assurance feedback tools and a flagging system that allows users to identify possible mistakes or areas that may need attention from someone with local knowledge.
Mapbox also has a dedicated data team that is committed to ensuring the quality of Mapbox maps and to adding and improving features all over the world. We also use an automated quarantine system that detects changes to the map that look like accidental editing mistakes or vandalism and stages them for manual review by our data team.
Attribution
When you publicly use styles or software that use Mapbox Streets vector tiles, you must display proper attribution.
A list of sources utilized in creating Mapbox Streets is available on the Mapbox website.
Multiple geometry types
Mapbox vector tiles support multiple geometry types in the same layer. Mapbox Streets v8 takes advantage of this in some layers.
A geometry in the vector tile can be one of three types:
In Mapbox Studio, you can select one, two, or all the three types with the Geometry Type toggles in each layer's data selection tab.
IDs
Each feature in a vector tile contains an object ID. This ID is not available for styling via Mapbox Studio, but can be used to interact with features at runtime with Mapbox GL JS and other vector tile libraries.
The ID is derived from a unique ID assigned to each feature by the relevant data vendor or Open Data project.
Often, multiple objects from the same or multiple proprietary sources are 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. In these cases the ID is either 0
or one of the input IDs chosen at random.
Data stability
As we make ongoing data updates to reflect changes in the world or integrate new data vendors, we may also add new layers, fields, and values to Mapbox Streets v8 tiles. Our goal is to do this in a way that preserves compatibility with existing v8 styles. 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
There are several fields that are used across several layers. These fields are detailed below instead of being duplicated for each relevant layer in the Layer reference section.
name
text and name_<lang-code>
text
Label names are available in many languages. The name_*
value is 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 the language-specific name_*
fields is also null. This means that name
should always be the final fallback value if you want to include it in your set of label languages.
If the name
field contains text to be rendered on multiple lines (horizontally or vertically) the text is separated by zero-width space characters.
Field | Description |
---|---|
name | The name (or names) used locally for the place |
name_ar | Arabic |
name_en | English |
name_es | Spanish |
name_fr | French |
name_de | German |
name_it | Italian |
name_pt | Portuguese |
name_ru | Russian |
name_zh-Hans | Simplified Chinese |
name_zh-Hant | Traditional Chinese (if available, but may contain some Simplified Chinese) |
name_ja | Japanese |
name_ko | Korean |
name_vi | Vietnamese |
For languages that may have regional variations, the tileset gives no particular preference where place name spellings differ.
name_es
, name_fr
, and name_de
labels, there are additional fallback conditions. Where the local name is in a non-Latin writing system and no Spanish, French, or German translation is available, these fields show an English or international version of the name if possible. Otherwise, they show the local name.Chinese: The name_zh-Hant
field contains Mandarin using simplified Chinese characters for our custom label layers: #place_label
and #natural_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-Hant
field. The name_zh-Hans
field is similar, except any traditional Chinese characters are automatically transformed to Simplified Chinese.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 is null if name
is also null.
sizerank
number
The sizerank
field is a value from 0-16 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 and filter based on the size of a feature relative to the current zoom level. The tileset assigns the largest objects sizerank=0
and assigns points sizerank=16
.
A single feature has 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 is never null and is always be within the range 0-16.
filterrank
number
The filterrank
field 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 is never null and is always in the range of 0-5.
maki
text
Some layers have a maki
field designed to make it easier to assign icons using the Maki icon project or 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 make sure 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 can sometimes have the same maki
value (for example universities and colleges, or art supply shops and art galleries). Nameless POIs always 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
maki_beta
text
Maki icons that might be supported in future versions of Mapbox Streets are in maki_beta
field. Possible values include, but not limited to:
poi_label
:
baseball
lighthouse
landmark
industry
highway-services
highway-rest-area
racetrack-cycling
racetrack-horse
racetrack-boat
racetrack
religious-shinto
observation-tower
restaurant-bbq
tunnel
natural_label
:
hot-spring
motorway_junction
:
interchange
junction
worldview
text
Mapbox Streets v8 introduces the notion of worldviews to the admin
, airport_label
, natural_label
, and place_label
data layers. The vector tiles contain multiple versions of some features, each with a worldview
value indicating the intended audience. When the worldview filter is applied, it must include both all
and one of the region-specific values. Additionally, for all worldviews except for US worldview, there are classes in respective layers, prefixed with disputed_
which user must select in conjunction with the worldview filter; classes in respective layers in US worldview do not have the disputed_
prefix.
A worldview filter must be applied to style layers that use the admin
data layer. It is highly recommended to also use a worldview filter with airport_label
, natural_label
, and place_label
data layers to communicate intent, but if no worldview is applied to those layers, the labels displayed on the map will reflect the US worldview.
worldview
field may be expanded. Changes may include both:- Introducing the current concept of worldview
to new or existing layers.- Adding new values to the list of possible worldview
values to represent other worldviews (see Data stability).worldview
value listed here (or any combination of values) necessarily reflects the official policy of any government or is approved by any government.Value | Description |
---|---|
all | Appropriate for all worldviews (most features) |
CN | Features for a mainland Chinese audience/worldview, but not officially approved for use in the PRC. |
IN | Features conforming to cartographic requirements for use in India. |
JP | Features for a Japanese audience, but which do not necessarily reflect official Japanese policy. |
US | Features for an American audience, but which do not necessarily reflect official US foreign policy. |
disputed_
class text {#disputed_-class-text}
Many layers have a class
field. These classes are often used to filter out or style features based on their purpose or characteristics. The available values for the class
field vary by layer and are detailed in the Layer Reference below.
In layers that have both a class
field and a worldview
field, the value for the class
field can be any value listed in the Layer Reference for that layer or any of those values prefixed with disputed_
. When a feature is marked as disputed, it falls under the disputed_{class}
class. For example, a disputed bay feature belongs to disputed_bay
class instead of bay
class.
disputed
text {#disputed-text}
While no single map will reflect all global perspectives, acknowledging disputes where they exist is an important aspect of cartography and can lead to more universally usable maps. The dispute
value will always be either true
or false
(never null). Any feature with a disputed_{class}
class will also have set disputed
to true
.
Layer Reference
The Mapbox Streets v8 tileset contains the following layers. For reference, the current minimum-available zoom level for each layer is mentioned, but note that this is subject to change as we roll out updates and improvements. It also does not apply to all features within a layer - only the most prominent features are available at lower-numbered zoom levels, and more features are available as you zoom in. Labels for physically-large features also have a maximum zoom level based on their size.
Layer | Min. zoom level |
---|---|
admin | 0 |
aeroway | 9 |
airport_label | 8 |
building | 13 |
housenum_label | 16 |
landuse_overlay | 5 |
landuse | 5 |
motorway_junction | 11 |
natural_label | 0 |
place_label | 0 |
poi_label | 5 |
road | 3 |
structure | 13 |
transit_stop_label | 11 |
water | 0 |
waterway | 7 |
admin
This layer contains boundary lines for national and subnational administrative units. The data source & shapes match polygons from the Mapbox Boundaries product.