Mapbox Boundaries v3

Access to Mapbox Boundaries

Access to the Mapbox Boundaries tilesets are controlled by Mapbox account access token. If you do not have access on your account, contact a Mapbox sales representative to request access to Boundaries tilesets.

Overview

Mapbox Boundaries is a family of vector tilesets that serve data visualization needs, allowing you to connect your own tabular data with a managed set of geographical features representing various types of boundaries such as administrative divisions or postal code areas.

The Mapbox Boundaries vector tiles only contain a minimal set of feature properties, which keeps them small and performant. Additional data such as names, hierarchy information, and official reference codes are provided in offline lookup tables that can be joined and referenced as needed.

Boundary types

Boundaries are grouped into five different types:

  • admin (adm): Divisions within a country or territory delineated for the purpose of 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 nonetheless 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 historical administrative boundaries that are still relevant for statistical uses.

Geometry types

Each individual Boundaries tileset will contain one of three geometry types:

Point
Linestring / multilinestring
Polygon / multipolygon

Points represent a central location within each boundary and can be used for labeling or symbolic data visualizations.

Lines represent the edge between two boundaries and allow for clean dashed line styles and special display of disputed boundaries.

Polygons represent the area covered by a boundary and can be used for choropleth visualizations, pattern fills, or hover and click interactions.

Tilesets

Mapbox Boundaries is composed of 29 separate tilesets, each with their own tileset ID with each individual tileset commonly referred to as a layer. Each tileset contains global data for that specific boundary type and level combination. An example is that 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 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 standard required number of digits to send mail".
Tileset IDData TypeGeometry TypeDescription
mapbox.boundaries-adm0-v3adminPolygonStates or territories that have ISO 3166-1 codes¹, and disputed areas
mapbox.boundaries-adm1-v3adminPolygonFirst-level administrative areas²
mapbox.boundaries-adm2-v3adminPolygonSecond-level administrative areas
mapbox.boundaries-adm3-v3adminPolygonThird-level administrative areas
mapbox.boundaries-adm4-v3adminPolygonFourth-level administrative areas
mapbox.boundaries-admLines-v3adminLineDivision lines for administrative levels 0-4
mapbox.boundaries-admPoints-v3adminPointPoint features for administrative levels 0-4
mapbox.boundaries-pos1-v3postalPolygonPostal code grouping areas
mapbox.boundaries-pos2-v3postalPolygonPostal code grouping areas
mapbox.boundaries-pos3-v3postalPolygonPostal code grouping areas
mapbox.boundaries-pos4-v3postalPolygonFull-detail postal code areas
mapbox.boundaries-posPoints-v3postalPointPoint features for postal levels 1-4
mapbox.boundaries-sta1-v3statsPolygonFirst-level statistical areas
mapbox.boundaries-sta2-v3statsPolygonSecond-level statistical areas
mapbox.boundaries-sta3-v3statsPolygonThird-level statistical areas
mapbox.boundaries-sta4-v3statsPolygonFourth-level statistical areas
mapbox.boundaries-sta5-v3statsPolygonFifth-level statistical areas
mapbox.boundaries-staPoints-v3statsPointPoint features for statistical levels 1-5
mapbox.boundaries-loc1-v3localityPolygonMetropolitan area
mapbox.boundaries-loc2-v3localityPolygonCity/Town/Village
mapbox.boundaries-loc3-v3localityPolygonDistrict/Quarter
mapbox.boundaries-loc4-v3localityPolygonNeighborhood
mapbox.boundaries-locPoints-v3localityPointLocality point features for levels 1-4
mapbox.boundaries-leg1-v3legislativePolygonConstituencies for national upper legislatures, unicameral legislatures, or similar
mapbox.boundaries-leg2-v3legislativePolygonConstituencies for national lower legislatures, or similar
mapbox.boundaries-leg3-v3legislativePolygonConstituencies for sub-national upper legislatures, unicameral legislatures, or similar
mapbox.boundaries-leg4-v3legislativePolygonConstituencies for sun-national lower legislatures, or similar
mapbox.boundaries-leg5-v3legislativePolygonConstituencies for local legislatures, councils, or similar
mapbox.boundaries-legPoints-v3legislativePointPoint features for legislative levels 1-5

¹ Two addtional areas are included: Kosovo, with code XK, and the UK Sovereign Base Areas of Akrotiri and Dhekelia, with code XS.
² Administrative level 2 generally contains external/dependent territories even if they are also included in level 0 due to having an ISO 3166-1 code.

Polygon Tileset Reference

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.

feature id

The feature id provides an identifier integer 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.

What is a Feature ID?

The id is a special property of a vector tile feature. It is always a whole number, and it is treated a little differently than normal feature properties. To reference an id in a Mapbox GL expression, you would write "id" rather than ["get", "property_name"] as you would use for normal properties.

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

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 style layers, otherwise your map will show conflicting and overlapping boundaries.

The worldview property will be either all or a comma-separated list of one or more ISO 3166-1 country codes, such as US or CN,JP. Since a single feature can belong to more than one worldview, you will need to use the "in" operator (as available in Mapbox GL JS 1.6.0 or later) to construct a layer filter. Below is an example filter to enable a US worldview - be sure to always include both all and one of the region-specific values.

[
  "any",
  ["==", "all", ["get", "worldview"]],
  ["in", "US", ["get", "worldview"]]
]

The supported region-specific worldviews are:

ValueDescription
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.
JPBoundaries conforming to cartographic requirements for use in Japan.
USBoundaries for an American audience, & which are generally appropriate outside of China & India. (Lines do not necessarily reflect official US foreign policy.)

Point Tileset Reference

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. In addition to those, 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 will be null if the name value is already in English or readable to English readers, meaning you may need to coalesce name_en and name for labeling or joining.

Line Tileset Reference

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 IDs of the polygons from either side of the line (sorted alphanumerically & separated by a hyphen).

level text

The level is a number from 0 through 4 representing the lowest-numbered level the boundary is a part of.

dispute 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). You should style boundary lines with a dispute value of true using a dashed or otherwise distinct style from non-disputed lines.

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

For boundaries with an level of 1 through 5, the iso_3166_1 value contains the id of the admin level 0 area that contains the boundary. For boundaries with a level of 0, the iso_3166_1 values is the same as the line id.

worldview text

Same as areas and points; see documentation above.

Was this page helpful?