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 layer points_postal_4 contains centroid point data for the mapbox.enterprise-boundaries-p4-v2 tileset.
• 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-v10',
  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 or stats 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 of a1.
• 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, or all).
• 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 of regions.
• 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:

1. A user identifies geographic dimensions in a data source, such as state, zip, country, or longitude & latitude.
2. A user makes a query from application data store.
3. Data store joins geographic dimension query results to metadata in the feature lookup table, such as name, unit_code, or level.
4. Data store groups and aggregates results by geographic dimension and sends to the client visualization tool.
5. Generate a Mapbox GL layer from the Mapbox Style Specification to create a visual from query results.
6. 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".

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.

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

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

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

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

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

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

Same as areas and points; see documentation above.