# Chuyển đổi địa chỉ cũ → mới

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

## Chuyển đổi địa chỉ cũ sang địa chỉ mới

![Chuyển đổi địa chỉ](https://maps.vietmap.vn/docs/assets/convert_address.webp)

Sau khi Việt Nam sáp nhập tỉnh thành và phường xã, mọi địa chỉ đang lưu trong hệ thống của bạn đều thành **địa chỉ cũ**. API này chuyển chúng sang **định dạng hành chính mới**, và chuyển ngược lại được khi cần.

Phản hồi đã tách sẵn: số nhà/đường trong `name`, từng cấp hành chính kèm `id` trong `boundaries` — ghi thẳng vào cột DB, không phải tự cắt chuỗi.

### Dùng vào việc gì

| Bài toán | Cách dùng |
| --- | --- |
| **Chuyển cả kho địa chỉ sang chuẩn mới** | Chạy vòng lặp qua từng bản ghi với `migrate_type=1`, lưu lại `display` và mảng `boundaries` |
| **Đối chiếu dữ liệu cũ với hệ thống đối tác** | Đối tác còn dùng địa chỉ cũ thì chuyển ngược bằng `migrate_type=2` |
| **Làm sạch địa chỉ người dùng nhập tay** | Địa chỉ gõ tay thường thiếu chuẩn; API trả về bản đã chuẩn hóa, tách phần |
| **Đồng bộ mã hành chính** | Lấy `id` trong `boundaries` làm khóa thay vì so khớp bằng tên phường/tỉnh |

!!! tip "Chuyển hàng loạt"
    API xử lý mỗi lượt gọi một địa chỉ. Muốn chuyển cả cơ sở dữ liệu thì gọi lặp và tôn trọng hạn mức lượt gọi của gói bạn đang dùng — xem [Giới hạn sử dụng](https://maps.vietmap.vn/docs/vi/map-api/console/usage-limitation/).

!!! tip "Thử ngay trên Playground"
    Gọi thử API chuyển đổi địa chỉ với dữ liệu thật, không cần viết code: **[Mở Playground](https://tools.vietmap.vn/playground/migrate-address)**

!!! tip "Tích hợp AI Agent :sparkles: MỚI"
    Tải bộ tài liệu đã tối ưu cho AI agent: **<a href="/docs/assets/agents/data-tools.txt" download="data-tools.txt">Data Tools Agent Doc</a>** · Schema máy đọc: **[OpenAPI 3.1](/docs/openapi.json)**

Hoặc dùng thử bằng [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**

### Tham số

|Tham số|Kiểu|Bắt buộc|Mô tả|Ví dụ|
|--- |--- |--- |--- |--- |
|apikey|string|có|API key VIETMAP cấp cho tài khoản của bạn. Đăng ký tại [đây](https://maps.vietmap.vn/console-v2/register)||
|focus|number|không|Tọa độ gần địa chỉ cần chuyển, định dạng `lat,lng`, dùng để phân biệt các địa chỉ trùng tên. **Bắt buộc khi `migrate_type=2`**|10.758867,106.675566|
|text|string|có|Địa chỉ cần chuyển đổi, gõ tự do. Nhận cả định dạng cũ lẫn mới|197 tran phu p4 q5|
|migrate_type|number|không|Chiều chuyển đổi. `1`: cũ → mới (mặc định dùng khi migrate dữ liệu). `2`: mới → cũ, **bắt buộc gửi kèm `focus`**|1|


### Ví dụ


**Đầu vào**
```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: Chạy ví dụ này trên 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 }

**Phản hồi (`migrate_type=1`, cũ → mới)**
```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"
        }
    ]
}
```

**Đầu vào**
```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: Chạy ví dụ này trên 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 }


**Phản hồi (`migrate_type=2`, mới → cũ)**
```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"
        }
    ]
}
```
### Mô tả phản hồi

| Trường   | Kiểu    | Mô tả                                                    |
| ----------- | ------- | -------------------------------------------------------------- |
| address     | string  | Phần hành chính của địa chỉ: phường/xã, quận/huyện (chỉ ở định dạng cũ), tỉnh/thành. Không gồm số nhà, tên đường. |
| name        | string  | Số nhà và tên đường, bóc ra từ `text`. |
| display     | string  | `name` + `address` ghép thành một chuỗi — dùng làm địa chỉ đầy đủ. |
| boundaries  | array   | Mảng các đơn vị hành chính của địa chỉ, xếp từ cấp nhỏ đến cấp lớn (phường/xã, quận/huyện, tỉnh/thành)    |

Với mảng `boundaries`:

| Trường con | Kiểu    | Mô tả                                    |
| ------------- | ------- | ---------------------------------------------- |
| type          | int     | Cấp hành chính (`0` = tỉnh/thành, `1` = quận/huyện, `2` = phường/xã) |
| id            | int     | Mã định danh của đơn vị hành chính             |
| name          | string  | Tên đơn vị hành chính, chưa kèm tiền tố                           |
| prefix        | string  | Tiền tố cấp hành chính. **Ví dụ:** `Phường`, `Quận`, `Thành Phố` |
| full_name     | string  | Tên đầy đủ gồm cả tiền tố. **Ví dụ:** `Phường 9` |

!!! tip "Gọi thử với dữ liệu của bạn"
    Nhập địa chỉ, toạ độ hoặc tham số của bạn và xem kết quả ngay trên bản đồ, kèm lệnh cURL để sao chép: **[Mở API chuyển đổi địa chỉ trên Playground](https://tools.vietmap.vn/playground/migrate-address)**