# Address Migration Documentation

Source: https://maps.vietmap.vn/docs/migrate-address/migrate-address-docs/

## Convert old addresses to the new format

![Convert Address](https://maps.vietmap.vn/docs/assets/convert_address.webp)

After Vietnam merged its provinces and wards, every address already stored in your system is an **old address**. This API converts them to the **new administrative format**, and back again when you need it.

The response comes pre-split: house number and street in `name`, each administrative level with its `id` in `boundaries` — write it straight into database columns, no string parsing.

### What you use it for

| Task | How |
| --- | --- |
| **Migrate a whole address database** | Loop over each record with `migrate_type=1` and store `display` plus the `boundaries` array |
| **Reconcile with a partner still on old addresses** | Convert the other way with `migrate_type=2` |
| **Clean up hand-typed addresses** | Free-text addresses are rarely well formed; the API returns a normalised, split version |
| **Sync administrative codes** | Use the `id` inside `boundaries` as the key instead of matching ward/province names as text |

!!! tip "Bulk conversion"
    The API handles one address per call. To migrate a whole database, loop and respect the rate limit of your plan - see [Usage Limits](https://maps.vietmap.vn/docs/map-api/console/usage-limitation/).

!!! tip "Try it in the Playground"
    Call the Address Migration API with real data, no code required: **[Open Playground](https://tools.vietmap.vn/playground/migrate-address)**

!!! tip "AI Agent Integration :sparkles: NEW"
    Download the optimized doc for AI agent integration: **<a href="/docs/assets/agents/data-tools.txt" download="data-tools.txt">Data Tools Agent Doc</a>** · Machine-readable schema: **[OpenAPI 3.1](/docs/openapi.json)**

Or try it in [Postman](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork).

### URL
```swift
https://maps.vietmap.vn/api/migrate-address/v3?apikey={your-apikey}&text={text}&focus={lat,long}
```

### Method
**GET**

### Parameters

|Parameter|Type|Required|Description|Example|
|--- |--- |--- |--- |--- |
|apikey|string|yes|API key provided by VIETMAP for your account. [Register here](https://maps.vietmap.vn/console-v2/register)||
|focus|number|no|A coordinate near the address, as `lat,lng`, used to disambiguate identical street names. **Required when `migrate_type=2`**|10.758867,106.675566|
|text|string|yes|Free-text address to convert. Accepts both the old and the new format|197 tran phu p4 q5|
|migrate_type|number|no|Conversion direction. `1`: old to new (what you use to migrate data). `2`: new to old, **requires `focus`**|1|


### Example


**Input**
```url
https://maps.vietmap.vn/api/migrate-address/v3?apikey={your-apikey}&text=197 tran phu p4 q5&focus=10.75887508,106.67538868
```

[:material-play-circle: Run this example on the Playground](https://tools.vietmap.vn/playground/migrate-address?text=197%20tran%20phu%20p4%20q5&focus=10.75887508,106.67538868&migrate_type=1){ .md-button .md-button--primary }

**Response (`migrate_type=1`, old → new)**
```json
{
    "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
    "name": "197 tran phu ",
    "display": "197 tran phu Phường Chợ Quán,Thành Phố Hồ Chí Minh",
    "boundaries": [
        {
            "type": 2,
            "id": 18700,
            "name": "Chợ Quán",
            "prefix": "Phường",
            "full_name": "Phường Chợ Quán"
        },
        {
            "type": 0,
            "id": 12,
            "name": "Hồ Chí Minh",
            "prefix": "Thành Phố",
            "full_name": "Thành Phố Hồ Chí Minh"
        }
    ]
}
```

**Input**
```url
https://maps.vietmap.vn/api/migrate-address/v3?apikey={your-apikey}&text=197 tran phu phuong cho quan tp ho chi minh&focus=10.75887508,106.67538868&migrate_type=2
```

[:material-play-circle: Run this example on the Playground](https://tools.vietmap.vn/playground/migrate-address?text=197%20tran%20phu%20phuong%20cho%20quan%20tp%20ho%20chi%20minh&focus=10.75887508,106.67538868&migrate_type=2){ .md-button .md-button--primary }


**Response (`migrate_type=2`, new → old)**
```json
{
    "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
    "name": "197 Trần Phú",
    "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
    "boundaries": [
        {
            "type": 2,
            "id": 656652,
            "name": "4",
            "prefix": "Phường",
            "full_name": "Phường 4"
        },
        {
            "type": 1,
            "id": 1292,
            "name": "5",
            "prefix": "Quận",
            "full_name": "Quận 5"
        },
        {
            "type": 0,
            "id": 12,
            "name": "Hồ Chí Minh",
            "prefix": "Thành Phố",
            "full_name": "Thành Phố Hồ Chí Minh"
        }
    ]
}
```
### Response description

| Parameter   | Type    | Description                                                    |
| ----------- | ------- | -------------------------------------------------------------- |
| address     | string  | Administrative part of the address: ward and city in the new format; ward, district and city in the old format. The street is in `name`. |
| name        | string  | House number and street, as parsed from `text`. |
| display     | string  | `name` and `address` joined into one string — store this as the full address. |
| boundaries  | array   | Administrative units of the address, from the smallest level up (ward, district, province)    |

For the `boundaries` array:

| Sub-Parameter | Type    | Description                                    |
| ------------- | ------- | ---------------------------------------------- |
| type          | int     | Administrative level (`0` = province/city, `1` = district, `2` = ward) |
| id            | int     | Unique identifier of the administrative unit             |
| name          | string  | Name of the administrative unit, without its prefix                           |
| prefix        | string  | Administrative level prefix. Example: `Phường`, `Quận`, `Thành Phố` |
| full_name     | string  | Full name including the prefix. Example: `Phường 9` |

!!! tip "Try it with your own data"
    Enter your own addresses, coordinates or parameters and see the result on a map, with a cURL command to copy: **[Open Address Migration on the Playground](https://tools.vietmap.vn/playground/migrate-address)**