All docsTilesetsReferenceMapbox Countries v1

Mapbox Countries v1

Source id:

This tileset reference document includes information to help you use the data in the Mapbox Countries v1 tileset.


Mapbox Countries v1 is a Mapbox-provided vector tileset that includes country level polygons from the Mapbox Boundaries premium tileset. Anyone can use the Mapbox Countries tileset to add global administrative country boundaries to maps and data visualizations.

Each global administrative level-0 boundary polygon is a territory identified by a unique ISO 3166-1 country code.

The tileset also includes individual polygons of major disputed areas and support for alternate boundary worldviews, which provides flexibility in how claimed international boundaries are displayed.

The tileset complements the mapbox-streets-v8 tileset, which contains corresponding line and point geometries for countries.

Boundary feedback

The country boundaries tileset is a subset of the Mapbox Boundaries product. To provide feedback on boundary issues, contact our Support team. To get access to more boundary levels, contact our Sales team.

Data sources

Data in the Mapbox Countries tileset is based on information obtained from officially recognized local or international entities.

Layer reference

This tileset contains one layer with polygon features and metadata.


min zoom level: 0buffer: 4

This layer contains the boundary polygons representing countries with a unique ISO 3166-1 code and global disputed areas.

Territory typeCount
Countries disputed='false'251
Disputed areas disputed='true'37

Associated land and maritime boundary lines for the polygons can be found in the admin layer. Centroid point labels can be found in the place_label layer of the mapbox-streets-v8 tileset.

feature id number

The feature ID provides an identifier integer for each feature and matches the IDs in the Mapbox Boundaries product.

Using names or ISO 3166-1 codes as feature IDs

For practical purposes like data joins, it may be convenient to use any of the other available properties as the feature ID. This can be done in Mapbox GL JS by setting the promoteId parameter while adding the vector tile source to the map.

disputed 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 disputed value will always be either true or false (never null). It is suggested to style disputed boundary polygons with a disputed value of true with using a fill-opacity value to make it semi transparent or otherwise distinct style from non-disputed areas.

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.

Refer to the Mapbox Boundaries worldview documentation for usage.

iso_3166_1 text

The iso_3166_1 property contains the ISO 3166-1 (Alpha-2 code) code of the boundary. These match the 249 offcially assigned country codes in the ISO 3166-1 standard except for:

  • XK Kosovo
  • XS Sovereign Base Areas (Akrotiri and Dhekelia)
  • D0<ISO><ISO><Number> Disputed area polygons will have the associated iso_3166_1 of the countries involved in the dispute preceeded by D0 code

iso_3166_1_alpha_3 text

The associated ISO 3166-1 (Alpha-3 code) as per ISO 3166 except for:

  • XKS Kosovo
  • XSB Sovereign Base Areas (Akrotiri and Dhekelia)
  • Not available for disputed areas

wikidata_id text

The unique Q number (QID) of the associated country in the Wikidata Database. This can be used to query the associated Wikidata item for translated country names and various other open data attributes.

name text

The local name for the country. Countries with multiple local languages may have local names separated by a hyphen.

name_en text

The commonly used English name for the country.

For displaying map labels, it is recommended to use the point labels available in the place_label layer of the mapbox-streets-v8 tileset.

region text

Region name for the country as defined in the UN M49 standard.

subregion text

Sub-region name for the country as defined in the UN M49 standard.

color_group number

A number between 1-6 assigned so that no adjacent countries have the same number. This can be used in an expression for creating a standard multi-color world political map.