Mapbox Boundaries v4
This reference documentation describes the technical specification of the Mapbox Boundaries v4 product.
See the change log for an overview of the latest changes, and the v3 to v4 migration guide for help with migrating your application from older versions.
Layer types and levels
As you begin working with Mapbox Boundaries, these are some of the key concepts you will want to understand:
- Layer types: Boundaries data is categorized into five broad layer types based on the functions the boundaries serve, such as administrative or postal:
- admin (
adm
): Divisions within a country or territory delineated for general administration. These usually have a capital and some type of government of their own, with the power to set laws and collect taxes throughout the division. - legislative (
leg
): Constituency areas for various types of legislative assemblies or regional councils. Typically voters elect a single representative to a larger body from each of these areas. - locality (
loc
): These are types of places that do not necessarily represent any official boundaries, but are commonly used as definitions of "place". - postal (
pos
): These are approximate areas of mail delivery based on national postal code systems. - stats (
sta
): These are non-administrative boundaries that are most commonly used for statistical purposes. These might be officially defined by a governmental statistical bureau, or they may be historical administrative boundaries that are still relevant for statistical uses.
- admin (
- Layer levels: Within each layer type, features are organized into a hierarchy of different numbered levels. Typically, larger-numbered levels will nest under smaller-numbered levels. For example. in the United States, counties (admin level 2) are subdivisions of states (admin level 1), which are subdivisions of the country (admin level 0). The number of levels available differ by country and data type.
- Administrative levels are anchored to the
adm0
layer, which contains the top-level polygon of each area that contains an ISO 3166-1 code. - Postal levels are anchored on the
pos4
level, which is defined as "Full-detail" or "The standard required number of digits to send mail".
- Administrative levels are anchored to the
Tilesets
The Mapbox Boundaries tilesets is composed of 29 separate tilesets, each with their own tileset ID. Each individual tileset is commonly referred to as a layer. Each tileset contains global data for that specific boundary type and level combination. For example, the administrative level 2 tileset will contain both US counties and Chinese prefectures.
For each data type, the hierarchy is designed such that levels with the lowest numbers generally contain the polygons with the largest areas and levels with the highest numbers contain the polygons with the smallest areas.
If you want to visualize any of the tilesets, layers, or worldviews to better understand the data type and level mapping for a country, see the boundaries explorer map.
Tileset IDs
Tileset ID | Layer Type-Level | Geometry Type | Description |
---|---|---|---|
mapbox.boundaries-adm0-v4 | admin-0 | Polygon | States or territories that have ISO 3166-1 codes, and disputed areas |
mapbox.boundaries-adm1-v4 | admin-1 | Polygon | First-level administrative areas |
mapbox.boundaries-adm2-v4 | admin-2 | Polygon | Second-level administrative areas |
mapbox.boundaries-adm3-v4 | admin-3 | Polygon | Third-level administrative areas |
mapbox.boundaries-adm4-v4 | admin-4 | Polygon | Fourth-level administrative areas |
mapbox.boundaries-admLines-v4 | admin-Lines | Line | Division lines for administrative levels 0-4 |
mapbox.boundaries-admPoints-v4 | admin-Points | Point | Point features for administrative levels 0-4 |
mapbox.boundaries-pos1-v4 | postal-1 | Polygon | Postal code grouping areas |
mapbox.boundaries-pos2-v4 | postal-2 | Polygon | Postal code grouping areas |
mapbox.boundaries-pos3-v4 | postal-3 | Polygon | Postal code grouping areas |
mapbox.boundaries-pos4-v4 | postal-4 | Polygon | Full-detail postal code areas |
mapbox.boundaries-posPoints-v4 | postal-Points | Point | Point features for postal levels 1-4 |
mapbox.boundaries-sta1-v4 | stats-1 | Polygon | First-level statistical areas |
mapbox.boundaries-sta2-v4 | stats-2 | Polygon | Second-level statistical areas |
mapbox.boundaries-sta3-v4 | stats-3 | Polygon | Third-level statistical areas |
mapbox.boundaries-sta4-v4 | stats-4 | Polygon | Fourth-level statistical areas |
mapbox.boundaries-sta5-v4 | stats-5 | Polygon | Fifth-level statistical areas |
mapbox.boundaries-staPoints-v4 | stats-Points | Point | Point features for statistical levels 1-5 |
mapbox.boundaries-loc1-v4 | locality-1 | Polygon | Metropolitan area |
mapbox.boundaries-loc2-v4 | locality-2 | Polygon | City/Town/Village |
mapbox.boundaries-loc3-v4 | locality-3 | Polygon | District/Quarter |
mapbox.boundaries-loc4-v4 | locality-4 | Polygon | Neighborhood |
mapbox.boundaries-locPoints-v4 | locality-Points | Point | Locality point features for levels 1-4 |
mapbox.boundaries-leg1-v4 | legislative-1 | Polygon | Constituencies for national upper legislatures, unicameral legislatures, or similar |
mapbox.boundaries-leg2-v4 | legislative-2 | Polygon | Constituencies for national lower legislatures, or similar |
mapbox.boundaries-leg3-v4 | legislative-3 | Polygon | Constituencies for sub-national upper legislatures, unicameral legislatures, or similar |
mapbox.boundaries-leg4-v4 | legislative-4 | Polygon | Constituencies for sub-national lower legislatures, or similar |
mapbox.boundaries-leg5-v4 | legislative-5 | Polygon | Constituencies for local legislatures, councils, or similar |
mapbox.boundaries-legPoints-v4 | legislative-Points | Point | Point features for legislative levels 1-5 |
Common fields
The following fields are included for every boundary feature in both the Boundaries tilesets and Boundaries lookup tables and are critical to enabling data joins, feature querying, and filtering.
mapbox_id
text {#mapbox_id-text}
The is the primary key for each feature in the Boundaries tilesets. The value is a globally unique object ID to enable data joins with the boundaries lookup tables. Features which have multiple worldviews share the same ID, but with a different worldview value.
mapbox_id
property is a breaking change from v3, which had integer id
values. Any reference to the id
or feature_id
values from v3 must be updated to use the new mapbox_id
values.Starting with v4, all Boundaries sources have to be added to the map using a promoteId
property to promote the mapbox_id
property as a feature-level id
to enable data joins. See the using Boundaries example for details.See the migration guide for additional information. iso_3166_1
text {#iso_3166_1-text}
The iso_3166_1
property contains the ISO 3166-1 code of each feature's administrative level 0 parent (or the feature itself in the case of the adm0
tileset). Besides the 249 two-character codes in the standard, the following values are available:
XK
KosovoXS
Sovereign Base Areas (Akrotiri and Dhekelia)
D0<ISO><ISO><Number>
Disputedadm0
level polygons and points will have the associatediso_3166_1
values of the countries involved in the dispute with by D0 prefix. Such features have an additional property ofdispute=true
.
The iso_3166_1
property is useful to filter features by the country or territory of interest.
worldview
text {#worldview-text}
The Boundaries vector tiles and feature lookup tables contain alternate representations of some boundaries in disputed areas, each with a worldview
value indicating the intended audience. It is important to apply a worldview filter to all your Boundaries data sources to avoid displaying conflicting and overlapping boundaries.
The worldview
property is either all
or a comma-separated list of one or more ISO 3166-1 country codes. The supported region-specific worldviews are:
Value | Description |
---|---|
all | Features common for all worldviews |
AR | Features for an Argentinian audience |
CN | Features for a mainland Chinese audience |
IN | Features for an Indian audience |
JP | Features for a Japanese audience |
MA | Features for a Moroccan audience |
RU | Features for a Russian audience |
TR | Features for a Turkish audience |
US | Features for an American audience |
Disclaimer: Mapbox worldviews have been internally reviewed for accuracy, but have not been officially endorsed by the respective countries.
See the using Boundaries example to apply a worldview filter to the map.
Polygon Source Layer
Polygons represent the area covered by a boundary and can be used for choropleth visualizations, pattern fills, or hover-and-click interactions.
boundaries_{type}_{level}
Each polygon tileset contains a single layer named boundaries_{type}_{level}
, where {type}
is one of the Boundary types, and {level}
is the level number.
mapbox_id
text {#polygon-mapbox_id-text}
Refer to Common fields
iso_3166_1
text {#polygon-iso_3166_1-text}
Refer to Common fields
worldview
text {#polygon-worldview-text}
Refer to Common fields
dispute
text {#polygon-dispute-text}
The admin-0
level polygon features representing internationally recognized disputed areas will have a value of dispute=true
. These features are useful to shade map areas affected by territorial disputes.
Point Source Layer
Points represent a central location within each boundary and can be used for labeling or symbolic data visualizations. There is one points tileset for each boundary type containing point geometries for all the features in the corresponding polygon tilesets. While the polygon tilesets are divided up by level, the points are collected into one tileset for all levels per boundary type.
points_{type}_{level}
Each point tileset contains layers named points_{type}_{level}
, where {type}
is a boundary type, and {level}
is a number 0
through 5
. The {type}
and {level}
values correspond to the given tileset.
The points_*
layers contain approximate center points corresponding to the polygons in the boundaries_*
layers. They can be used for labeling or for visualizations using symbols. Points are generally available one zoom level lower than the polygons they correspond to.
The point layers have the same feature ID, iso_3166_1
, and worldview
properties as the polygon layers with the same meaning. Name properties are also provided.
name
text {#point-name-text}
The name
property contains the name of each feature, if any. The name is usually in a local or official language of the region or country.
name_en
text {#point-name_en-text}
The name_en
property contains the English name of each feature, if any. Often the name_en
value is null if the name
value is already in English or readable to English readers, meaning you might need to coalesce name_en
and name
for labeling or joining.
mapbox_id
text {#point-mapbox_id-text}
Refer to Common fields
iso_3166_1
text {#point-iso_3166_1-text}
Refer to Common fields
worldview
text {#point-worldview-text}
Refer to Common fields
dispute
text {#point-dispute-text}
The admin-0
level point features representing internationally recognized disputed areas will have a value of dispute=true
. These features are useful to label corresponding disputed polygons.
Line Source Layer
Lines represent the edge between two boundaries and allow for clean dashed line styles and special display of disputed boundaries.
boundaries_admin_lines
Only the administrative (adm
) boundary type is available as line data. The administrative lines tileset contains a single layer containing boundary lines for all administrative levels (adm0
through adm4
).
id
text {#line-id-text}
Boundary line IDs are usually composed by combining the mapbox_id
of the polygons from either side of the line (sorted alphanumerically and separated by a hyphen).
level
text {#line-level-text}
The level
is a number from 0 through 4 representing the lowest-numbered level the boundary is part of.
coastal
text {#line-coastal-text}
The coastal
field contains the text true
or false
indicating whether the boundary is along a coast or not. Most coastal boundaries are omitted from the line layer, so the values are nearly always false
.