Mapbox Boundaries v4

Join the Mapbox Developers Discord Communityarrow-right

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.
• 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 adm0 layer, which contains the top-level polygon of each area that contains an ISO 3166-1 code.
  • Postal levels are anchored on the pos4 level, which is defined as "Full-detail" or "The standard required number of digits to send mail".

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

Admin levels for dependent territories

Non-sovereign dependent territories (for example, Greenland) having their own ISO 3166-1 code are duplicated across both admin-0 and admin-1, indicating dual status as both a level-0 territory and as a dependent territory of another sovereign state. This means first-level subdivisions start at admin-2 for such territories rather than admin-1.

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.

Migrating from v3

The string 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:

• XK Kosovo
• XS Sovereign Base Areas (Akrotiri and Dhekelia)

• D0<ISO><ISO><Number> Disputed adm0 level polygons and points will have the associated iso_3166_1 values of the countries involved in the dispute with by D0 prefix. Such features have an additional property of dispute=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}

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.

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}

markerpolylinepolygon

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

markerpolylinepolygon

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.

Migrating from v3

JSON lookup tables have been deprecated in v4 in favor of CSV. This enables greater flexibility for users to parse and manipulate the lookup tables for your application. Several fields have also been renamed in v4 for consistency.See the migration guide for additional information.

• 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 the mapbox_id reference for details.

• layer_type: The data layer type (for example, admin, postal, or stats). 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 of adm1.
• 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 when name is not in a Latin based script, otherwise may be null.
• name_translations: 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_0: The mapbox_id of the admin-level-0 parent of a feature.
• parent_1: The mapbox_id of the level-1 parent of a feature, if any.
• parent_2: The mapbox_id of the level-2 parent of a feature, if any.
• parent_3: The mapbox_id of the level-3 parent of a feature, if any.
• parent_4: The mapbox_id of 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 the source-layer within 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 the source-layer within the point tileset containing the feature.
• area_sqkm: Approximate area of the feature in square kilometers.

Join the Mapbox Developers Discord Communityarrow-right

Was this page helpful?