Mapbox Boundaries v2
Mapbox users who have access to Mapbox Boundaries can add global administrative, postal, and statistical boundaries to their maps and data visualizations. This guide covers how to use Mapbox Boundaries in a web application and navigate feature lookup tables.
Add Boundaries v2 to an application
Once you have access to Mapbox Boundaries, you can use them in an application as you would use any other tileset.
About Mapbox Boundaries v2
Below you'll find a few pieces of key information that you'll need to navigate the Mapbox Boundaries tileset.
Tileset IDs
Mapbox Boundaries are stored as vector tiles and distributed via the Mapbox Vector Tiles API, with a unique tileset for each admin, stats, and postal level. Tileset IDs for Boundaries tilesets are in the form mapbox.enterprise-boundaries-{a|p|s}{level}-{version}
. Here are a few examples:
mapbox.enterprise-boundaries-a0-v2
: The tileset for admin (a
) level 0 (0
) boundaries (which contain countries) in version two (v2
) of Mapbox Boundaries.mapbox.enterprise-boundaries-p1-v2
: The tileset for postal (p
) level 1 (1
) boundaries in version two (v2
) of Mapbox Boundaries.mapbox.enterprise-boundaries-s3-v2
: The tileset for stats (s
) level 3 (3
) boundaries in version two (v2
) of Mapbox Boundaries.
Find the complete list of Mapbox Boundaries tilesets and read more about tileset hierarchies in the Boundaries v2 reference.
Feature IDs
Each feature also has a unique ID that is used to identify a feature polygon. Once Boundaries are added to your account, you will be able to access the reference documentation containing the feature IDs and all identifying metadata.
Minimum zoom levels and bounding boxes
- z_min: The
z_min
value for each feature indicates the minimum zoom level at which a feature is available in a tileset. Use this to set the camera to a minimum zoom level to see the feature. - centroid point: Centroid point features are guaranteed to appear at zoom level
z_min
+ 1. Centroid point features can be used to display a marker, symbol, or label at the center of a Boundaries feature.- Access vector tiles containing centroid points for a specific admin, postal, or stat level using the tileset ID as described above and specifying the source layer
points_{admin|postal|stats}_{level}
. For example, the vector tile source layerpoints_postal_4
contains centroid point data for themapbox.enterprise-boundaries-p4-v2
tileset.
- Access vector tiles containing centroid points for a specific admin, postal, or stat level using the tileset ID as described above and specifying the source layer
- bounds: Feature bounds are the smallest rectangular envelope that a feature fits into denoted as an array of
[min_long, min_lat, max_long, max_lat]
.
Example
To use a Mapbox Boundaries tileset in your application, make a request from the Mapbox Vector Tiles API for the relevant tileset. For example, in Mapbox GL JS, load the tileset using the code below:
// Be sure to use an access token from an account
// that has access to Boundaries.
mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
var map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/light-v11',
center: [-99.9, 41.5],
zoom: 1
});
map.on('load', function() {
// Add source for admin-0 Boundaries.
map.addSource('admin-0', {
type: 'vector',
url: 'mapbox://mapbox.enterprise-boundaries-a0-v2'
});
// Add a layer with boundary lines.
map.addLayer({
id: 'admin-0-line',
type: 'line',
source: 'admin-0',
'source-layer': 'boundaries_admin_0',
paint: {
'line-color': 'red',
'line-width': ['interpolate', ['linear'], ['zoom'], 0, 2, 20, 10]
}
}, 'waterway-label');
// Add a layer with points.
map.addLayer({
id: 'admin-0-circle',
type: 'circle',
source: 'admin-0',
'source-layer': 'points_admin_0',
paint: {
'circle-color': 'white',
'circle-stroke-color': 'black',
'circle-stroke-width': ['interpolate', ['linear'], ['zoom'], 0, 2, 20, 6],
'circle-radius': ['interpolate', ['linear'], ['zoom'], 0, 2, 20, 20]
}
}, 'waterway-label');
});
The code above will yield a map with all country boundaries in red with a circle at the center of each country.
Feature lookup tables
Each boundary feature is indexed in a lookup table. Lookup tables are designed to be used locally in your application. User data can be joined to Mapbox Boundaries in your application to create a visualization, such as a choropleth map of unemployment by state.
About feature lookup tables
The Mapbox Boundaries lookup tables include this metadata about each polygon feature:
- id: globally unique identifier for the feature.
- id_int: an integer-only identifier for a feature that can be used to create data-joins with Mapbox GL JS's feature state.
- type: either
admin
,postal
orstats
to represent the Administrative, Postal or Statistical boundaries types in Mapbox Boundaries. - level: a numeric value between 0 and 5 to represent the level of boundaries within the type.
- layer: a shortened concatenation of type and level with feature's administrative (
a
), postal (p
), or statistical (s
) hierarchy and level (0-5
). For example, administrative level 1 would have a level ofa1
. - tilesetname: tileset ID for the tileset containing the feature, see the Boundaries v2 reference for more details.
- worldview: alternate display of administrative units depending on regional map display requirements (
US
,CN
,IN
, orall
). - unit_code: the country-specific identifier for the feature, such as postcode or FIPS code.
- name: local feature name.
- name_ascii: local feature name converted to ascii characters.
- names: an array that contains any translation or aliases for that boundary.
- description: a text qualifier of the level respective to each country's boundary hierarchy. For example, US admin-1 boundaries have a description of
states
while Italian admin-1 boundaries have a description ofregions
. - wikidata_id: the associated Wikidata ID for the boundary.
- source_date: recency of boundary data.
- iso_3166_1_alpha_3: the ISO-3 country code for the feature.
- parent_0: the level-0 parent of a feature, which corresponds to the ISO-2 country code.
- parent_1: the level-1 parent of a feature, if it exists.
- parent_2: the level-2 parent of a feature, if it exists.
- parent_3: the level-3 parent of a feature, if it exists.
- parent_4: the level-4 parent of a feature, if it exists.
- z_min: minimum zoom level at which a polygon feature appears in a tileset.
- centroid: The centroid of the boundary in
[long, lat]
format. - bounds: an array of the features bounding box as
[minlong, minlat, maxlong, maxlat]
. - polylayername: name of the source-layer within the tileset containing feature polygon geometry.
- pointlayername: name of the source-layer within the tileset containing feature centroid.
Lookup tables are available as JSON.
Sample workflow
The feature lookup tables are designed to be used alongside the Mapbox Boundaries tilesets. A typical workflow for a business intelligence application is:
- A user identifies geographic dimensions in a data source, such as state, zip, country, or longitude & latitude.
- A user makes a query from application data store.
- Data store joins geographic dimension query results to metadata in the feature lookup table, such as
name
,unit_code
, orlevel
. - Data store groups and aggregates results by geographic dimension and sends to the client visualization tool.
- Generate a Mapbox GL layer from the Mapbox Style Specification to create a visual from query results.
- The visual style definition works the same across all Mapbox GL products, including Mapbox GL JS on the web, and Mapbox GL Native on iOS, Android, macOS, and Qt.
Example
Read the Visualize the USA’s economic recovery with client-side data joins blog post, which illustrates how the steps in the sample workflow can work in your application.
Boundaries v2 reference
The Mapbox Boundaries vector tiles do not directly contain detailed feature properties such as names or parent boundary information. Such detailed data is delivered separately as offline lookup tables, allowing the vector tiles to stay small and performant.
Key concepts
There are a few key concepts to get familiar with as you start working with Mapbox Boundaries.
- Data types. Mapbox Boundaries data is categorized into several broad types based on the functions the boundaries serve, such as administrative or postal. See the Boundaries v2 reference for a list of supported data types and their definitions.
- Data levels. Within each data 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 will differ by country and data type.
- Tileset IDs. Mapbox Boundaries are stored as vector tiles and distributed via the Mapbox Vector Tiles API, with unique tilesets for each combination of data type and level. Tileset IDs for Boundaries tilesets are in the form
mapbox.boundaries-{type}{level}-{version}
. See the Boundaries reference for a full list of all the available tileset IDs. - Feature IDs. Each feature has a numeric identifier that is unique across all the Mapbox Boundaries tilesets.
- Feature lookup tables. Mapbox Boundaries vector tiles contain feature shapes and IDs, but most of the other parts of the data are only available as separate JSON or CSV files. To make full use of Mapbox Boundaries you need to work with a combination of vector tilesets, the provided lookup tables, and your own custom data.
Tilesets
Mapbox Boundaries is composed of 15 separate tilesets, each with their own tileset ID. There are two types of tilesets: tilesets containing line features and tilesets containing polygon features. For area tilesets, the hierarchy is designed such that levels with lowest numbers generally contain the polygons with the largest areas and levels with the highest numbers contain the polygons with the smallest areas.
Some other notes about tileset hierarchy:
- Administrative levels are anchored to the
a0
layer which contains the top-level polygon of each area which contains an ISO 3166-1 code. - Postal levels are anchored on the
p4
level which is defined as "Full-detail" or "The minimum required number of digits to send mail".
Tileset ID | Description |
---|---|
mapbox.enterprise-boundaries-a0-v2 | States or territories that have ISO 3166-1 codes, plus Kosovo |
mapbox.enterprise-boundaries-a1-v2 | First-level administrative areas |
mapbox.enterprise-boundaries-a2-v2 | Second-level administrative areas |
mapbox.enterprise-boundaries-a3-v2 | Third-level administrative areas |
mapbox.enterprise-boundaries-a4-v2 | Fourth-level administrative areas |
mapbox.enterprise-boundaries-a5-v2 | Fifth-level administrative areas |
mapbox.enterprise-boundaries-aL-v2 | Administrative division lines for all levels |
mapbox.enterprise-boundaries-p1-v2 | Postal code grouping areas |
mapbox.enterprise-boundaries-p2-v2 | Postal code grouping areas |
mapbox.enterprise-boundaries-p3-v2 | Postal code grouping areas |
mapbox.enterprise-boundaries-p4-v2 | Full-detail postal code areas |
mapbox.enterprise-boundaries-s1-v2 | First-level statistical areas |
mapbox.enterprise-boundaries-s2-v2 | Second-level statistical areas |
mapbox.enterprise-boundaries-s3-v2 | Third-level statistical areas |
mapbox.enterprise-boundaries-s4-v2 | Fourth-level statistical areas |
Geometry types
Each layer in Enterprise Boundary tilesets will contain one of 3 geometry types:
Area Layer Reference
boundaries_{type}_{level}
Each area tileset has a layer named boundaries_{type}_{level}
, where {type}
is one of admin
, postal
, or stats
, and {level}
is a number 0
through 5
. The {type}
and {level}
values correspond to the given tileset.
id
text
The id
field provides an identifier string for each feature. These IDs are globally unique within a given “worldview”; some are duplicated but only where they represent different versions of the same feature for different worldviews.
worldview
text
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 your admin
style layers, otherwise your map will show conflicting and overlapping boundary lines. The filter should always include both all
and one of the region-specific values.
Value | Description |
---|---|
all | Appropriate for all worldviews (most boundaries). |
CN | Boundaries for a mainland Chinese audience/worldview, but not officially approved for use in the PRC. |
IN | Boundaries conforming to cartographic requirements for use in India. |
US | Boundaries for an American audience, & which are generally appropriate outside of China & India. (Lines do not necessarily reflect official US foreign policy.) |
points_{type}_{level}
Each area tileset has a layer named points_{type}_{level}
, where {type}
is one of admin
, postal
, or stats
, 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 two id
and worldview
fields as the area layers with the same meaning.
Administrative Line Layer Reference
boundaries_admin_lines
The administrative lines tileset contains a single layer containing boundary lines for all administrative levels (a0
through a5
).
id
text {#line-id-text}
Boundary line IDs are usually composed by combining the IDs of the polygons from either side of the line (sorted alphanumerically & separated by a hyphen).
admin_level
text {#line-admin_level-text}
The admin_level
is a number from 0 through 5 representing the lowest-numbered administrative level the boundary is a part of.
disputed
text {#line-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 reflect all global perspectives, but acknowledging disputes where they exist is an important aspect of good cartography. The value will always be either true
or false
(never null).
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
.
parent_0
text {#line-parent_0-text}
For boundaries with an admin_level
of 1 through 5, the parent_0
value contains the id
of the level 0 area that contains the boundary. For boundaries with an admin_level
of 0, the parent_0
is the same as the line id
.
worldview
text {#line-worldview-text}
Same as areas and points; see documentation above.