All docsMapbox BoundariesGuidesBoundaries v3 to v4 migration

Boundaries v3 to v4 migration

This guide walks through the process of migrating your application from Mapbox Boundaries v3 to Mapbox Boundaries v4.

Before migrating, see the change log for an overview of the major changes in this release.

Breaking API changes

Mapbox IDs

The v4 release introduces a new format of stable and globally unique identifiers, mapbox_id, for each feature in the boundaries tilesets and lookup tables.

Because IDs are the primary key for joins between the lookup tables and tileset features, this is a significant breaking change that impacts all existing v3 applications.

v3 IDsv4 IDs
Field namefeature_idmapbox_id
Mapbox GL property["id"]["get","mapbox_id"]
Unique IDUnique within Boundaries productUnique across all Mapbox products
Example value12345dXJuOm1ieGJuZDpSQkJCOnY0
Migration guide


  • For data joins to boundaries vector tiles to work correctly, the v4 boundary tilesets source must always be added in Mapbox GL using the promoteId option. This promotes the mapbox_id property to be used as the feature-level IDs to enable data joins. See the basic example for details.

Note: Usage of promoteId requires Mapbox GL JS v1.7+ Mapbox Maps iOS v10.0+ Mapbox Maps Android v10.0+


  • Any references to the v3 feature_id primary keys stored in the system must be remapped to the new v4 primary key mapbox_id using the v4 lookup tables
    • If your application does not use layers affected by breaking data changes, you can update v3 feature_id values to v4 mapbox_id values using the TILESET_v3_v4_id_mapping.csv lookup tables in your delivery.
  • Any references to the v3 feature_id field in the lookup tables need to be changed to mapbox_id. Account for the format change from integer to string type.
  • If using the Tilequery API for querying the Boundary tilesets, any references to the id property in the response have to be changed from response.features[].id in v3 tilesets to response.features[].properties.mapbox_id in v4 tilesets.

Lookup table file format

The v4 lookup tables are only be delivered in CSV format. JSON files are no longer be available.

Migration guide

If you use the JSON lookup files in your pipeline, use csvjson to transform the CSV to a JSON structure as needed. This enables greater flexibility in structuring the lookup file for your application.

Lookup table field names

Several field names in the lookup tables have been renamed for improved consistency and readability. 

Migration guide

Use the following change table of v3 and v4 lookup table field names to update references to these fields as required.

v3 field namev4 field nameChange

Breaking data changes

Several geographies are affected by data changes that are not backwards compatible with v3 and do not have a one-to-one mapping of IDs from v3 to v4.

Migration guide

Review the following tables of layer changes to determine if your application is affected. References to features in affected layers must be migrated using the v4 lookup tables.

Countryv3 Layerv4 LayerReason for change
American SamoaAS-stats-3Shift levels to be equivalent to US-stats
American SamoaAS-stats-3AS-stats-4Shift levels to be equivalent to US-stats
American SamoaAS-stats-4AS-stats-5Shift levels to be equivalent to US-stats
BrazilBR-stats-2Refreshed with new statistical boundaries
BrazilBR-stats-3Refreshed with new statistical boundaries
CambodiaKH-postal-1New data level
CambodiaKH-postal-4New data level
Saudi ArabiaSA-postal-2New data level
El SalvadorSV-postal-4New data level
GuamGU-stats-3Shift levels to be equivalent to US-stats
GuamGU-stats-3GU-stats-4Shift levels to be equivalent to US-stats
GuamGU-stats-4GU-stats-5Shift levels to be equivalent to US-stats
IcelandIS-admin-1IS-stats-4Regions are statistical and not administrative
IcelandIS-admin-2IS-admin-1Municipalities are first level administirative divisions
IndiaIN-admin-3Refreshed with latest subdistrict boundaries
IndonesiaID-admin-3Refreshed with latest boundaries
IndonesiaID-admin-4Refreshed with latest boundaries
JapanJP-admin-3JP-admin-2Fix JP-admin-2 placeholder level
JapanJP-admin-4JP-admin-3Fix JP-admin-2 placeholder level
LuxembourgLU-stats-4LU-admin-1Cantons are first level administirative divisions
LuxembourgLU-admin-1LU-admin-2Communes are second level administirative divisions
MalaysiaMY-admin-2Introduce new MY-admin-2 level for divisions in Sabah and Sarawak state
MalaysiaMY-admin-2MY-admin-3Introduce new MY-admin-2 level for divisions in Sabah and Sarawak state
SerbiaRS-stats-1New data level for NUTS
SerbiaRS-stats-1RS-stats-2New data level for NUTS
SerbiaRS-stats-3New data level for NUTS
South KoreaKR-admin-3Introduce new KR-admin-3 level for municipal districts
South KoreaKR-admin-3KR-admin-4Introduce new KR-admin-3 level for municipal districts
TurkmenistanTM-postal-3Introduce new 4-digit postcodes for TM-postal-3
TurkmenistanTM-postal-3TM-postal-2Introduce new 4-digit postcodes for TM-postal-3
UkraineUA-admin-2Refreshed with reorganized boundaries
UkraineUA-admin-3New data level with reorganized boundaries
UkraineUA-admin-4New data level for municipal districts
United StatesUS-postal-3Introduce new 3-digit postcodes for US-postal-3
United StatesUS-postal-3US-postal-2Introduce new 3-digit postcodes for US-postal-3
United StatesUS-stats-3Refreshed with 2020 census boundaries
United StatesUS-stats-4Refreshed with 2020 census boundaries
United StatesUS-stats-5Refreshed with 2020 census boundaries
United StatesUS-legislative-1US-legislative-1Placholder for redistricting boundaries
United StatesUS-legislative-2US-legislative-2Placholder for redistricting boundaries
United StatesUS-legislative-3US-legislative-3Placholder for redistricting boundaries
United StatesUS-legislative-4US-legislative-4Placholder for redistricting boundaries
United StatesUS-locality-1US-locality-1Dropped due to duplication with US-stats-2
United StatesUS-locality-2Refreshed with expanded data coverage
United StatesUS-locality-3Refreshed with expanded data coverage
United StatesUS-locality-4Refreshed with expanded data coverage
VietnamVN-postal-3Refreshed with new postcode system
VietnamVN-postal-4Refreshed with new postcode system


The US Legislative layers are not present with the Boundaries v4.0 first release. We are waiting until the official legislative updates are published and made available to the public in late 2022. Once available, we will include the new US legislative data in the next minor release.

Migration guide

If US-legislative layers are critical, it is suggested to wait for the v4.1 release for the latest 2022 boundaries. Older legislative boundaries are only be available in the v3 tilesets.


All US locality layers have been updated and reorganized for parity with the Mapbox Search API.

v3 US-locality Layersv4 US-locality Layers
MetropolitanRemoved - Duplicative of stats 1&2
DistrictsLocality (sub-city level CDPs, rural hamlets, non-postal features)

Migration resources

v3 to v4 ID mapping tables

The breaking change to primary key identifiers requires all existing v3 feature_id values to be updated to the v4 mapbox_id values. IDs of feature in layers not affected by breaking data changes can be quickly updated with v4 IDs using the ID mapping files provided in your delivery.

The mapping file is formatted as a CSV with the following fields:

  • v3_feature_id integer: The deprecated integer primary key value for features in v3.
  • v3_id string: The deprecated string primary key value for features in v3.
  • v3_iso_3166_1 string: The ISO 3166-1 country/territory code of the feature in v3
  • v3_data_type string: See layer types and levels for details.
  • v3_level integer: See layer types and levels for details.
  • v4_mapbox_id string: The new primary key value for features in v4.
  • v4_iso_3166_1 string: The ISO 3166-1 country/territory code of the feature in v4. These will mostly be unchanged in except for some disputed areas.
  • v4_layer_type string: Analagous to data_type in v3. Layer type in v4 will be unchanged except for features that have shifted to a new type indicated in breaking data changes
  • v4_layer_level integer: Analagous to level in v3. Layer level in v4 will be unchanged except for features that have shifted to a new level indicated in breaking data changes.
Migration guide

Use the ID mapping CSV files to migrate references in your database or application that use the feature_id, iso_3166_1, data_type and level values from the v3 lookup tables to the new values in the v4 lookup tables.

For v3 features that are not present in v4, their v4 values will be empty in the ID mapping files. These references might either need to be deleted in your database or migrated to the closest match using the v4 lookup tables.