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. To help compare data coverage between the versions, you can make use of Boundaries Explorer v4 and Boundaries Explorer v3.
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 IDs | v4 IDs | |
|---|---|---|
| Field name | feature_id | mapbox_id |
| Mapbox GL property | ["id"] | ["get","mapbox_id"] |
| Type | integer | string |
| Unique ID | Unique within Boundaries product | Unique across all Mapbox products |
| Example value | 12345 | dXJuOm1ieGJuZDpSQkJCOnY0 |
Migration guide
Maps
- For data joins to boundaries vector tiles to work correctly, the v4 boundary tilesets source must always be added in Mapbox GL using the
promoteIdoption. This promotes themapbox_idproperty to be used as the feature-level IDs to enable data joins. See the basic example for details._Note: Usage ofpromoteIdrequiresMapbox GL JS v1.7+Mapbox Maps iOS v10.0+Mapbox Maps Android v10.0+
IDs
- Any references to the v3
feature_idprimary keys stored in the system must be remapped to the new v4 primary keymapbox_idusing the v4 lookup tables - If your application does not use layers affected by breaking data changes, you can update v3
feature_idvalues to v4mapbox_idvalues using theTILESET_v3_v4_id_mapping.csv lookup tablesin your delivery. - Any references to the v3
feature_idfield in the lookup tables need to be changed tomapbox_id. Account for the format change fromintegertostringtype. - If using the Tilequery API for querying the Boundary tilesets, any references to the
idproperty in the response have to be changed fromresponse.features[].idin v3 tilesets toresponse.features[].properties.mapbox_idin 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 name | v4 field name | Change |
|---|---|---|
| id | Deleted | |
| feature_id | Deleted | |
| mapbox_id | Added | |
| type | layer_type | Renamed |
| level | layer_level | Renamed |
| layer | layer_name | Renamed |
| worldview | ||
| unit_code | ||
| name | ||
| name_en | ||
| names | name_translations | Renamed |
| description | ||
| wikidata_id | ||
| source_date | ||
| iso_3166_1_alpha_3 | ||
| iso_3166_1 | ||
| grouping_attributes | ||
| join_atrributes | ||
| parent_0 | Added | |
| parent_1 | ||
| parent_2 | ||
| parent_3 | ||
| parent_4 | ||
| z_min | polygon_z_min | Renamed |
| point_z_min | Added | |
| centroid | ||
| bounds | bbox | Renamed |
| polytilesetname | polygon_tileset_id | Renamed |
| polylayername | polygon_source_layer | Renamed |
| pointtilesetname | point_tileset_id | Renamed |
| pointlayername | point_source_layer | Renamed |
| area_sqkm |
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.
| Country | v3 Layer | v4 Layer | Reason for change |
|---|---|---|---|
| American Samoa | AS-stats-3 | Shift levels to be equivalent to US-stats | |
| American Samoa | AS-stats-3 | AS-stats-4 | Shift levels to be equivalent to US-stats |
| American Samoa | AS-stats-4 | AS-stats-5 | Shift levels to be equivalent to US-stats |
| Brazil | BR-stats-2 | Refreshed with new statistical boundaries | |
| Brazil | BR-stats-3 | Refreshed with new statistical boundaries | |
| Cambodia | KH-postal-1 | New data level | |
| Cambodia | KH-postal-4 | New data level | |
| Canada | CA-locality-4 | New data level | |
| Saudi Arabia | SA-postal-2 | New data level | |
| El Salvador | SV-postal-4 | New data level | |
| Guam | GU-stats-3 | Shift levels to be equivalent to US-stats | |
| Guam | GU-stats-3 | GU-stats-4 | Shift levels to be equivalent to US-stats |
| Guam | GU-stats-4 | GU-stats-5 | Shift levels to be equivalent to US-stats |
| Iceland | IS-admin-1 | IS-stats-4 | Regions are statistical and not administrative |
| Iceland | IS-admin-2 | IS-admin-1 | Municipalities are first level administirative divisions |
| India | IN-admin-3 | Refreshed with latest subdistrict boundaries | |
| Indonesia | ID-admin-3 | Refreshed with latest boundaries | |
| Indonesia | ID-admin-4 | Refreshed with latest boundaries | |
| Japan | JP-admin-3 | JP-admin-2 | Fix JP-admin-2 placeholder level |
| Japan | JP-admin-4 | JP-admin-3 | Fix JP-admin-2 placeholder level |
| Luxembourg | LU-stats-4 | LU-admin-1 | Cantons are first level administirative divisions |
| Luxembourg | LU-admin-1 | LU-admin-2 | Communes are second level administirative divisions |
| Malaysia | MY-admin-2 | Introduce new MY-admin-2 level for divisions in Sabah and Sarawak state | |
| Malaysia | MY-admin-2 | MY-admin-3 | Introduce new MY-admin-2 level for divisions in Sabah and Sarawak state |
| Serbia | RS-stats-1 | New data level for NUTS | |
| Serbia | RS-stats-1 | RS-stats-2 | New data level for NUTS |
| Serbia | RS-stats-3 | New data level for NUTS | |
| South Korea | KR-admin-3 | Introduce new KR-admin-3 level for municipal districts | |
| South Korea | KR-admin-3 | KR-admin-4 | Introduce new KR-admin-3 level for municipal districts |
| Turkmenistan | TM-postal-3 | Introduce new 4-digit postcodes for TM-postal-3 | |
| Turkmenistan | TM-postal-3 | TM-postal-2 | Introduce new 4-digit postcodes for TM-postal-3 |
| Ukraine | UA-admin-2 | Refreshed with reorganized boundaries | |
| Ukraine | UA-admin-3 | New data level with reorganized boundaries | |
| Ukraine | UA-admin-4 | New data level for municipal districts | |
| United States | US-postal-3 | Introduce new 3-digit postcodes for US-postal-3 | |
| United States | US-postal-3 | US-postal-2 | Introduce new 3-digit postcodes for US-postal-3 |
| United States | US-stats-3 | Refreshed with 2020 census boundaries | |
| United States | US-stats-4 | Refreshed with 2020 census boundaries | |
| United States | US-stats-5 | Refreshed with 2020 census boundaries | |
| United States | US-legislative-1 | US-legislative-1 | Refreshed with 2020 census redistricted boundaries |
| United States | US-legislative-2 | US-legislative-2 | Refreshed with 2020 census redistricted boundaries |
| United States | US-legislative-3 | US-legislative-3 | Refreshed with 2020 census redistricted boundaries |
| United States | US-legislative-4 | US-legislative-4 | Refreshed with 2020 census redistricted boundaries |
| United States | US-locality-1 | US-locality-1 | Dropped due to duplication with US-stats-2 |
| United States | US-locality-2 | Refreshed with expanded data coverage | |
| United States | US-locality-3 | Refreshed with expanded data coverage | |
| United States | US-locality-4 | Refreshed with expanded data coverage | |
| Vietnam | VN-postal-3 | Refreshed with new postcode system | |
| Vietnam | VN-postal-4 | Refreshed with new postcode system |
US-Legislative
The US legislative layers were removed in the v4.0 release and re-introduced in version v4.1 based on the decennial redistricting data program from the 2020 Census.
US-Locality
All US locality layers have been rebuilt and reorganized for data parity with the Mapbox Search API.
| Layer | v3 US-locality Layers | v4 US-locality Layers |
|---|---|---|
| locality-1 | Metropolitan Areas | Removed - Duplication of stats-2 |
| locality-2 | Cities and CDPs | Place |
| locality-3 | Districts | Locality (sub-city level CDPs, rural hamlets, non-postal features) |
| locality-4 | Neighborhoods | Neighborhoods |
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_idinteger: The deprecated integer primary key value for features in v3.v3_idstring: The deprecated string primary key value for features in v3.v3_iso_3166_1string: The ISO 3166-1 country/territory code of the feature in v3v3_data_typestring: See layer types and levels for details.v3_levelinteger: See layer types and levels for details.v4_mapbox_idstring: The new primary key value for features in v4.v4_iso_3166_1string: 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_typestring: Analagous todata_typein v3. Layer type in v4 will be unchanged except for features that have shifted to a new type indicated in breaking data changesv4_layer_levelinteger: Analagous tolevelin 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. Was this page helpful?