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

# Boundaries v3 to v4 migration

This guide walks through the process of migrating your application from [Mapbox Boundaries v3](https://docs.mapbox.com/data/boundaries/reference/mapbox-boundaries-v3/) to [Mapbox Boundaries v4](https://docs.mapbox.com/data/boundaries/reference/mapbox-boundaries-v4/).

Before migrating, see the [change log](https://docs.mapbox.com/data/boundaries/changelog/#v40) 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](https://demos.mapbox.com/boundaries-explorer/) and [Boundaries Explorer v3](https://demos.mapbox.com/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` |

> **Note: 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 [`promoteId`](https://docs.mapbox.com/style-spec/reference/sources/#vector-promoteId) option. This promotes the `mapbox_id` property to be used as the feature-level IDs to enable data joins. See the [basic example](https://docs.mapbox.com/data/boundaries/guides/use-boundaries/#basic-example) for details._Note: Usage of `promoteId` requires `Mapbox GL JS v1.7+` `Mapbox Maps iOS v10.0+` `Mapbox Maps Android v10.0+`
> 
> **IDs**
> 
> -   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](https://docs.mapbox.com/data/boundaries/reference/mapbox-boundaries-v4#lookup-tables)
> -   If your application does not use layers affected by [breaking data changes](#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](https://docs.mapbox.com/api/maps/tilequery/) 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.

> **Note: Migration guide**
> 
> If you use the JSON lookup files in your pipeline, use [`csvjson`](https://csvkit.readthedocs.io/en/latest/scripts/csvjson.html) 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. 

> **Note: 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.

> **Note: 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](https://docs.mapbox.com/data/boundaries/reference/mapbox-boundaries-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](https://www.census.gov/programs-surveys/decennial-census/about/rdo.html) from the 2020 Census.

### US-Locality

All US locality layers have been rebuilt and reorganized for data parity with the [Mapbox Search API](https://docs.mapbox.com/api/search/).

| 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](#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](https://docs.mapbox.com/data/boundaries/reference/mapbox-boundaries-v4#layer-types-and-levels) for details.
-   **`v3_level`** *integer*: See [layer types and levels](https://docs.mapbox.com/data/boundaries/reference/mapbox-boundaries-v4#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](#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](#breaking-data-changes).

> **Note: 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.