Legacy

This guide discusses a deprecated version of Mapbox Boundaries. For the most updated version, see Mapbox Boundaries v4.

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.

Basic example

To add Mapbox Boundaries to a Mapbox GL JS map, use map.addSource to add a Boundaries tileset to the map, then use map.addLayer to apply a style to the data. Here is an example adding the admin-1 polygon tileset and styling it with a basic fill.


map.on('load', function() {

  // Add source for admin-1 Boundaries
  map.addSource('admin-1', {
    type: 'vector',
    url: 'mapbox://mapbox.boundaries-adm1-v3'
  });

  // Add a layer with boundary polygons
  map.addLayer(
    {
      id: 'admin-1-fill',
      type: 'fill',
      source: 'admin-1',
      'source-layer': 'boundaries_admin_1',
      paint: {
        'fill-color': '#CCCCCC'
      }
    },
    // This final argument indicates that we want to add the Boundaries layer
    // before the `waterway-label` layer that is in the map from the Mapbox
    // Light style. This ensures the admin polygons will be rendered on top of
    // the
    'waterway-label'
  );
});

Add a worldview filter

The Mapbox Boundaries tilesets provide multiple worldview options in each tileset. That means that there are multiple versions of certain features, each intended for a different audience. Filters on each style layer determine which worldview you show.

You should add a worldview filter to every Boundaries layer you add to a map. Since you might add more Boundaries layers to a project later, it makes sense to define the filter as a variable. This example uses a variable called worldviewFilter:


map.on('load', function() {

  // Add source for admin-1 Boundaries
  map.addSource('admin-1', {
    type: 'vector',
    url: 'mapbox://mapbox.boundaries-adm1-v3'
  });

  var worldviewFilter = [
    "any",
    ["==", "all", ["get", "worldview"]],
    ["in", "US", ["get", "worldview"]]
  ];

  // Add a layer with boundary polygons
  map.addLayer(
    {
      id: 'admin-1-fill',
      type: 'fill',
      source: 'admin-1',
      'source-layer': 'boundaries_admin_1',
      filter: worldviewFilter,
      paint: {
        'fill-color': '#CCCCCC'
      }
    },
    // This final argument indicates that we want to add the Boundaries layer
    // before the `waterway-label` layer that is in the map from the Mapbox
    // Light style. This ensures the admin polygons will be rendered on top of
    // the
    'waterway-label'
  );
});

This creates a map style with Mapbox Boundaries that's ready to have custom data joined into it.

Reference

Worldviews

The worldview property will be 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 respective countries.

Vector tilesets

Same as v4 tileset ids, but with the v3 version suffix.

Tileset schema

Polygon tilesets `boundaries_{type}_{level}`

markerpolylinepolygon

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

See worldviews for details.

Feature lookup tables

The Mapbox Boundaries lookup tables are JSON and CSV files that are delivered to you when you buy access to Boundaries. They provide extra information about features that is not directly available in the vector tiles.

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 best suits your solution.

The lookup tables are organized by data type and level and are provided in both JSON and CSV format. The different formats contain the same information, so you can use whichever one is better suited to your workflow.

Boundary identifiers

Every boundary feature is assigned a unique integer feature id in the vector tiles and is cross referenced by a corresponding feature_id in the feature lookup table.

Field descriptions

The Mapbox Boundaries lookup tables include this metadata about each polygon and point feature:

id: A string identifier for the feature that is globally unique within a worldview. For most functionality that deals with the vector tiles you should use feature_id instead. These are provided for backwards compatibility with Boundaries v2 and are likely to be deprecated in favor of feature_id in the future.
feature_id: The integer ID used for each feature in the vector tiles. It can be used for data-joins with Mapbox GL JS's feature state. Like id, it is globally unique within a worldview.
type: The data type (for example admin, postal, or stats). See the Boundary types for a full list of values and definitions.
level: A numeric value between 0 and 5 that shows the level of boundaries within the type. (Note: different data types have different level ranges available.)
layer: 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 of adm1.
worldview: Used to display alternate boundary data depending on regional map display requirements. See the Boundaries reference for an explanation of possible values.
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 when name is not in a Latin based script, otherwise may be null.
names: An array that contains additional translations or aliases for the feature name. May be null.
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. May be null, 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_1: The id of the level-1 parent of a feature, if any.
parent_2: The id of the level-2 parent of a feature, if any.
parent_3: The id of the level-3 parent of a feature, if any.
parent_4: The id of the level-4 parent of a feature, if any.
z_min: The minimum zoom level at which a polygon feature appears in a tileset.
centroid: An approximate central point of the feature's polygon as an array of [longitude, latitude].
bounds: 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.
polytilesetname: The tileset ID for the tileset containing the feature's polygon. See the list of tilesets for more details.
polylayername: The name of the source-layer within the polygon tileset containing the feature.
pointtilesetname: The tileset ID for the tileset containing the feature's point. See the list of tilesets for more details.
pointlayername: The name of the source-layer within the point tileset containing the feature.

Format

CSV

Boundaries with alternate worldview representations will have multiple entries and can be correctly targeted using the corresponding worldview property.


// Header row
layer,type,level,polytilesetname,polylayername,pointtilesetname,pointlayername,id,feature_id,wikidata_id,worldview,unit_code,name,name_en,names,description,source_date,iso_3166_1_alpha_3,iso_3166_1,grouping_attributes,join_attributes,parent_1,parent_2,parent_3,parent_4,z_min,area_sqkm,centroid,bounds

JSON

In the nested JSON structure, individual boundary entries will be keyed by their unique string id value in the <layer>.data.all path, while boundaries with alternate worldview representations will be available in the corresponding <layer>.data.<worldview> path.


// Sample entry from admin-0 lookup table
{
    "adm0":{
       "type":"admin",
       "level":0,
       "PolyTilesetName":"mapbox.boundaries-adm0-v3",
       "PolyLayerName":"boundaries_admin_0",
       "PointTilesetName":"mapbox.boundaries-admPoints-v3",
       "PointLayerName":"points_admin_0",
       "data":{
          "all":{
             "AD":{
                "feature_id":331777,
                "wikidata_id":"Q228",
                "worldview":"all",
                "unit_code":"AD",
                "name":"Andorra",
                "names":{
                   "ar":[
                      "أندورا"
                   ],
                   "ca":[
                      "Andorra",
                      "Principat d'Andorra",
                      "el país dels Pirineus",
                      "les Valls d'Andorra"
                   ],
                   "de":[
                      "Andorra"
                   ],
                   "en":[
                      "AND",
                      "Andorra",
                      "Principality of Andorra",
                      "Principality of the Valleys of Andorra",
                      "ad",
                      "🇦🇩"
                   ],
                   "es":[
                      "Andorra",
                      "Principado de Andorra"
                   ],
                   "fr":[
                      "Andorre"
                   ],
                   "it":[
                      "Andorra"
                   ],
                   "ja":[
                      "アンドラ"
                   ],
                   "ko":[
                      "안도라"
                   ],
                   "pt":[
                      "Andorra"
                   ],
                   "ru":[
                      "Андорра"
                   ],
                   "vi":[
                      "Andorra"
                   ],
                   "zh-Hans":[
                      "安道尔"
                   ],
                   "zh-Hant":[
                      "安道爾"
                   ]
                },
                "description":"state",
                "source_date":"2016",
                "iso_3166_1_alpha_3":"AND",
                "iso_3166_1":"AD",
                "grouping_attributes":{
                   "UN M49 Region":[
                      "Europe"
                   ],
                   "UN M49 Sub-region":[
                      "Southern Europe"
                   ]
                },
                "join_attributes":{
                   "UN M49 Sub-region code":"039",
                   "UN M49 Region code":"150"
                },
                "z_min":0,
                "centroid":[
                   1.5893,
                   42.5425
                ],
                "bounds":[
                   1.4138,
                   42.4288,
                   1.7865,
                   42.6549
                ],
                "area_sqkm":629
             }
             ...more boundaries
          }
          ...more worldviews
       }
    }
 }

Additional Developer Resources

Mapbox Developer Discord

Developer Cheatsheet

Mapbox Support

Ask AI

Was this page helpful?

Basic example​

Add a worldview filter​

Reference

Worldviews​

Vector tilesets​

Tileset schema​

Polygon tilesets boundaries_{type}_{level}​

feature id​

iso_3166_1 text​

worldview text​

Feature lookup tables​

Boundary identifiers​

Field descriptions​

Format​