> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/data/tilesets/llms.txt)

# Mapbox Countries v1

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

## Overview

**Mapbox Countries v1** is a free, Mapbox-provided vector tileset of [high resolution country polygons](https://medium.com/mapbox/high-resolution-administrative-country-polygons-in-studio-57cf4abb0768) derived from the [Mapbox Boundaries](https://www.mapbox.com/boundaries) product. Any Mapbox user can use the tileset for use cases like [creating country masks](https://www.mapbox.com/blog/masking-in-studio-using-high-resolution-administrative-country-polygons) or [choropleth data visualizations](https://docs.mapbox.com/mapbox-gl-js/example/data-join/).

The tileset includes vector polygon features for all countries and territories defined in the [ISO 3166-1 country code standard](https://www.iso.org/obp/ui#search), including [alternate worldviews](#polygon-worldview-text) for flexibility in how claimed international boundaries are displayed for a regional audience.

### Access this Tileset

Use this **Tileset URL** to add this tileset to your map style as a `vector` source:

```text
mapbox://mapbox.country-boundaries-v1
```

Access this tileset's [TileJSON](https://docs.mapbox.com/help/glossary/tilejson/):

```text
https://api.mapbox.com/v4/mapbox.country-boundaries-v1.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN
```

Access tiles from this tileset via the [Vector Tiles API](https://docs.mapbox.com/api/maps/vector-tiles/) using the following template:

```text
https://api.mapbox.com/v4/mapbox.country-boundaries-v1/{z}/{x}/{y}.{format}?access_token=YOUR_MAPBOX_ACCESS_TOKEN
```

Query this tileset at a specific location using the [Tilequery API](https://docs.mapbox.com/api/maps/tilequery/):

```text
https://api.mapbox.com/v4/mapbox.country-boundaries-v1/tilequery/{longitude},{latitude}.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN
```

> **Note: Boundary feedback**
> 
> The country boundaries tileset is a subset of the [Mapbox Boundaries](https://docs.mapbox.com/data/boundaries/guides/) product. To provide feedback on boundary issues, contact our [Support team](https://support.mapbox.com/). To get access to more boundary levels, contact our [Sales team](https://www.mapbox.com/contact/sales/).

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

### `country_boundaries`

min zoom level: 0buffer: 4

This layer contains the boundary polygons representing all countries and territories with a unique ISO 3166-1 code.

| Territory type | Feature count |
| --- | --- |
| Countries `disputed='false'` | 251 |
| Disputed areas `disputed='true'` | 41 |

These polygons complement the [`mapbox-streets-v8`](https://docs.mapbox.com/vector-tiles/reference/mapbox-streets-v8/) tileset, which contains associated [land and maritime boundary lines](https://docs.mapbox.com/data/tilesets/reference/mapbox-streets-v8#admin) and [point labels](https://docs.mapbox.com/data/tilesets/reference/mapbox-streets-v8#place_label) for each country.

#### feature `id` *number*

A unique object ID assigned to each country. Duplicate IDs will be present on features if a country has alternate worldview representations. For stable identifiers, use `mapbox_id`.

> **Note: 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. To achieve this in Mapbox GL JS, you set the [promoteId](https://docs.mapbox.com/style-spec/reference/sources/#vector-promoteId) parameter when adding the vector tile source to the map.

#### `mapbox_id` *text*

The globally unique Mapbox ID is the alphanumeric primary key for each feature and [corresponds to the Mapbox Boundaries v4 IDs](https://docs.mapbox.com/data/boundaries/reference/mapbox-boundaries-v4#mapbox_id-text).

#### `disputed` *text*

Countries recognized in the ISO 3166-1 standard have a value of `'false'` while overlay polygons of disputed areas have a value of `'true'`.

We suggest styling disputed boundary polygons with `disputed='true'` as a separate style layer. Use a fill-opacity value to make it semi transparent or otherwise distinct style from non-disputed areas.

This example [GL filter expression](https://docs.mapbox.com/help/glossary/filter/) can be used to only display country polygons without any disputed areas:

```json
[
  "==",
  ["get", "disputed"],
  "false"
]
```

#### `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 to avoid showing conflicting and overlapping boundaries.

This example GL filter expression builds on the [disputed area expression](#polygon-disputed-text) to display all `disputed='false'` country boundaries matching a worldview for either `US` or `all` audiences:

```json
[
  "all",
  [
    "==",
    ["get", "disputed"],
    "false"
  ],
  [
    "any",
    [
      "==",
      "all",
      ["get", "worldview"]
    ],
    [
      "in",
      "US",
      ["get", "worldview"]
    ]
  ]
]
```

Refer to the [Mapbox Boundaries worldview documentation](https://docs.mapbox.com/data/boundaries/reference/mapbox-boundaries-v4#worldview-text) for available worldviews.

#### `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 officially assigned country codes in the [ISO 3166-1 standard](https://www.iso.org/obp/ui#iso:pub:PUB500001:en) and the following two unofficial codes:

-   `XK` Kosovo
-   `XS` Sovereign Base Areas (Akrotiri and Dhekelia)

For disputed area polygons with `disputed='true'`, the code is in the `D0<ISO><ISO><Number>` format, which indicates the `iso_3166_1` code of the two or more countries involved in the disputed claim.

#### `iso_3166_1_alpha_3` *text*

The associated ISO 3166-1 (Alpha-3 code) as per [ISO 3166](https://www.iso.org/obp/ui#search) except for:

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

#### `wikidata_id` *text*

The unique [QID](https://www.wikidata.org/wiki/Wikidata:Glossary#QID) of the associated country in the [Wikidata Database](https://www.wikidata.org/wiki/Wikidata:Main_Page). 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](https://docs.mapbox.com/data/tilesets/reference/mapbox-streets-v8#place_label) of the `mapbox-streets-v8` tileset.

#### `region` *text*

Region name for the country as defined in the [UN M49 standard](https://unstats.un.org/unsd/methodology/m49/overview/).

#### `subregion` *text*

Sub-region name for the country as defined in the [UN M49 standard](https://unstats.un.org/unsd/methodology/m49/overview/).

#### `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.