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
adm0layer, which contains the top-level polygon of each area that contains an ISO 3166-1 code. - Postal levels are anchored on the
pos4level, 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
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
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:
XKKosovoXSSovereign Base Areas (Akrotiri and Dhekelia)
D0<ISO><ISO><Number>Disputedadm0level polygons and points will have the associatediso_3166_1values 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
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
Refer to Common fields
iso_3166_1 text
Refer to Common fields
worldview text
Refer to Common fields
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
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
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
Refer to Common fields
iso_3166_1 text
Refer to Common fields
worldview text
Refer to Common fields
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
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
The level is a number from 0 through 4 representing the lowest-numbered level the boundary is part of.
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.
iso_3166_1 text
Refer to Common fields
worldview text
Refer to Common fields
dispute text
While no single map reflects 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 is always either true or false (never null). You should style boundary lines with a dispute value of true using a dashed or otherwise distinct style from non-disputed lines.
Lookup Tables
The Mapbox Boundaries lookup tables are flat CSV files that are delivered to you when you buy access to Boundaries. The lookup tables include the full metadata for every feature in the Boundaries tilesets.
Each boundary feature is indexed in a lookup table. Lookup tables are designed to be used locally in your application. They are delivered as flat files so they can be customized, parsed down, and adjusted in a way that suits your solution.
The lookup tables are organized by data type and level, following the naming convention of the Boundaries tileset IDs.
GeoJSON Files
When you buy a flat file license, the Mapbox Boundaries GeoJSON files give you access to the raw geometry and metadata for boundaries features delivered as compressed .geojsonl files. The GeoJSON files contain the same metadata properties as the CSV fields.
The GeoJSON files are organized by data type and level, following the naming convention of the Boundaries tileset IDs.
CSV fields
The Mapbox Boundaries lookup tables include this metadata about each polygon and point feature.
mapbox_id: The unique object ID used for each feature in the vector tiles that is globally unique within a worldview. It can be used for data-joins with Mapbox GL JS's feature state. See themapbox_idreference for details.
layer_type: The data layer type (for example,admin,postal, orstats). See the Boundary layer types and levels for a full list of values and definitions.layer_level: A numeric value between 0 and 5 that shows the data layer level of boundaries within the type. (Note: different data types have different level ranges available.)layer_name: A shortened concatenation of type and level with feature's administrative (adm), postal (pos), or statistical (sta) hierarchy and level (0-5). For example, administrative level 1 would have a level ofadm1.worldview: Used to display alternate boundary data depending on regional map display requirements. See the worldview reference for details.unit_code: The country-specific identifier for the feature, such as postcode or FIPS code.name: The local feature name.name_en: An English translation or Latin transliteration of the local name. Generally only provided whennameis not in a Latin based script, otherwise may benull.name_translations: An array that contains additional translations or aliases for the feature name. May benull.description: A text qualifier of the level respective to each country's boundary hierarchy. For example, US admin-1 boundaries have a description ofstateswhile Italian admin-1 boundaries have a description ofregions.wikidata_id: The associated Wikidata ID for the boundary. May benull, as not all features can be directly associated with Wikidata entities.source_date: Recency of boundary data.iso_3166_1_alpha_3: The ISO 3166-1 alpha-3 country code for the feature's parent country or territory.iso_3166_1: The ISO 3166-1 alpha-2 country code for the feature's parent country or territory.grouping_attributes: A JSON object with properties that allows associating the feature to relevant geographic groups like UN M49 regions for countries (admin-0).join_atrributes: A JSON object with properties that allows associating the feature to relevant geographic codes like UN M49 regions for countries (admin-0) and ISO 3166-2 subdivision codes for admin-1 or admin-2 polygons.parent_0: Themapbox_idof the admin-level-0 parent of a feature.parent_1: Themapbox_idof the level-1 parent of a feature, if any.parent_2: Themapbox_idof the level-2 parent of a feature, if any.parent_3: Themapbox_idof the level-3 parent of a feature, if any.parent_4: Themapbox_idof the level-4 parent of a feature, if any.polygon_z_min: The minimum zoom level at which a polygon feature appears in a polygon tileset.point_z_min: The minimum zoom level at which a point feature appears in a point tileset.centroid: An approximate central point of the feature's polygon as an array of[longitude, latitude].bbox: An array of the features bounding box as[minlong, minlat, maxlong, maxlat]. Longitude values for features crossing the date line will be outside the(-180:180)range.polygon_tileset_id: The tileset ID for the tileset containing the feature's polygon. See the list of tilesets for more details.polygon_source_layer: The name of thesource-layerwithin the polygon tileset containing the feature.point_tileset_id: The tileset ID for the tileset containing the feature's point. See the list of tilesets for more details.point_source_layer: The name of thesource-layerwithin the point tileset containing the feature.area_sqkm: Approximate area of the feature in square kilometers.