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

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

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.

Điểm quan trọng: API trả về địa chỉ đã tách sẵn từng phần kèm mã đơn vị hành chính, nên bạn ghi thẳng vào cột trong cơ sở dữ liệu chứ 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

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.

Dùng thử tại đây: Công cụ chuyển đổi địa chỉ

Tích hợp AI Agent MỚI

Tải bộ tài liệu đã tối ưu cho AI agent: Data Tools Agent Doc

URL

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
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

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

Phản hồi

Ví dụ phản hồi với migrate_type=1 (cũ sang mới)

{
    "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

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

Ví dụ phản hồi với migrate_type=2 (mới sang cũ)

{
    "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	Địa chỉ đầy đủ gồm street, ward và city.
name	string	Tên của địa điểm/địa chỉ
display	string	Tên hiển thị chứa đầy đủ thông tin của địa chỉ
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