REST API miễn phí cho developer

Address Converter API

Tài liệu tích hợp API tra cứu và chuyển đổi địa chỉ hành chính Việt Nam trước và sau sáp nhập. Nội dung chính luôn khả dụng, schema Swagger sẽ tự bổ sung khi backend phản hồi.

Base URL

https://api.tracuudiachi.io.vn/api/v1

Swagger JSON: https://api.tracuudiachi.io.vn/docs-json

POST/api/v1/convert-address

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

Example

curl -X POST https://api.tracuudiachi.io.vn/api/v1/convert-address \
  -H "Content-Type: application/json" \
  -d '{
    "province_code": 1,
    "district_code": 1,
    "ward_code": 1
  }'

POST/api/v1/search-new-address

Tra cứu địa chỉ mới

Example

curl -X POST https://api.tracuudiachi.io.vn/api/v1/search-new-address \
  -H "Content-Type: application/json" \
  -d '{
    "province_code": 1,
    "ward_code": 256
  }'

POST/api/v1/bulk-convert-address

Upload Excel chuyển đổi hàng loạt

Example

curl -X POST https://api.tracuudiachi.io.vn/api/v1/bulk-convert-address \
  -F "file=@addresses.xlsx"

Endpoint chính

Tìm theo nhóm, method, đường dẫn hoặc mô tả endpoint.

Convert

POST/api/v1/convert-address

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

Nhận mã tỉnh, huyện, xã cũ và trả về địa chỉ mới sau sáp nhập.

Request body

Example

{
  "province_code": 1,
  "district_code": 1,
  "ward_code": 1
}

Response example

Example

{
  "status": true,
  "message": "Chuyển đổi địa chỉ thành công.",
  "data": {
    "old_address": {
      "province_code": 1,
      "province_name": "Thành phố Hà Nội",
      "district_code": 1,
      "district_name": "Quận Ba Đình",
      "ward_code": 1,
      "ward_name": "Phường Phúc Xá"
    },
    "new_addresses": [
      {
        "province_code": 1,
        "province_name": "Thành phố Hà Nội",
        "ward_code": 101,
        "ward_name": "Phường Ba Đình"
      }
    ]
  }
}

POST/api/v1/search-new-address

Tra cứu địa chỉ mới

Nhận mã tỉnh và mã xã/phường mới để lấy thông tin địa chỉ tương ứng.

Request body

Example

{
  "province_code": 1,
  "ward_code": 256
}

Response example

Example

{
  "status": true,
  "message": "Lấy thông tin địa chỉ mới thành công.",
  "data": {
    "province_code": 1,
    "province_name": "Thành phố Hà Nội",
    "ward_code": 256,
    "ward_name": "Phường Ba Đình"
  }
}

POST/api/v1/bulk-convert-address

Chuyển đổi hàng loạt bằng Excel

Upload file Excel bằng field form-data tên "file". File cần có cột Tỉnh/Thành phố, Quận/Huyện, Phường/Xã.

Request body

Example

{
  "file": "addresses.xlsx"
}

Response example

Example

{
  "status": true,
  "message": "Xử lý file Excel thành công.",
  "data": [
    {
      "index": 0,
      "status": true,
      "data": {
        "old_address": {},
        "new_addresses": []
      }
    }
  ]
}

Provinces

GET/api/v1/provinces

Danh sách tỉnh/thành phố cũ

Hỗ trợ phân trang và mở rộng quan hệ districts, wards.

Query

pageicppexpand=districts,wards

Response example

Example

{
  "data": [],
  "meta": {
    "total": 0,
    "page": 1,
    "icpp": 20,
    "totalPages": 0
  }
}

GET/api/v1/provinces/:code

Chi tiết tỉnh/thành phố cũ

Lấy một tỉnh/thành phố cũ theo mã hành chính.

Query

expand=districts,wards

Response example

Example

{
  "data": {
    "code": 1,
    "name": "Thành phố Hà Nội"
  }
}

GET/api/v1/new-provinces

Danh sách tỉnh/thành phố mới

Hỗ trợ phân trang và mở rộng quan hệ wards.

Query

pageicppexpand=wards

Response example

Example

{
  "data": [],
  "meta": {
    "total": 0,
    "page": 1,
    "icpp": 20,
    "totalPages": 0
  }
}

Districts

GET/api/v1/districts

Danh sách quận/huyện cũ

Hỗ trợ phân trang và mở rộng quan hệ wards, province.

Query

pageicppexpand=wards,province

Response example

Example

{
  "data": [],
  "meta": {
    "total": 0,
    "page": 1,
    "icpp": 20,
    "totalPages": 0
  }
}

GET/api/v1/provinces/:provinceCode/districts

Danh sách quận/huyện theo tỉnh cũ

Lấy danh sách quận/huyện cũ thuộc một tỉnh/thành phố.

Query

expand=wards

Response example

Example

{
  "data": []
}

Wards

GET/api/v1/wards

Danh sách phường/xã cũ

Hỗ trợ phân trang và mở rộng quan hệ district, province.

Query

pageicppexpand=district,province

Response example

Example

{
  "data": [],
  "meta": {
    "total": 0,
    "page": 1,
    "icpp": 20,
    "totalPages": 0
  }
}

GET/api/v1/new-wards

Danh sách phường/xã mới

Hỗ trợ phân trang danh sách phường/xã sau sáp nhập.

Query

pageicpp

Response example

Example

{
  "data": [],
  "meta": {
    "total": 0,
    "page": 1,
    "icpp": 20,
    "totalPages": 0
  }
}

GET/api/v1/new-provinces/:provinceCode/new-wards

Danh sách phường/xã mới theo tỉnh

Lấy danh sách phường/xã mới thuộc một tỉnh/thành phố mới.

Query

expand=province

Response example

Example

{
  "status": true,
  "message": "Lấy danh sách Phường/Xã thành công.",
  "data": []
}

Swagger dynamic schema

Phần này đọc trực tiếp từ backend tại https://api.tracuudiachi.io.vn/docs-json. Nếu backend hoặc CORS chưa sẵn sàng, các tài liệu tĩnh phía trên vẫn dùng được.

Đang tải Swagger JSON...

Tại sao chọn Address Converter?

Độ chính xác cao

Đảm bảo 99.8% độ chính xác với cơ sở dữ liệu cập nhật liên tục theo quy định mới nhất

Xử lý nhanh chóng

Chuyển đổi hàng nghìn địa chỉ chỉ trong vài giây với thuật toán tối ưu

API miễn phí

Tích hợp dễ dàng vào ứng dụng của bạn với API RESTful hoàn toàn miễn phí

Câu hỏi thường gặp

Công cụ này có miễn phí không?

Hoàn toàn miễn phí! Bạn có thể sử dụng không giới hạn cho cả chuyển đổi đơn lẻ và API.

Độ chính xác của chuyển đổi như thế nào?

Chúng tôi đảm bảo độ chính xác 99.8% với cơ sở dữ liệu được cập nhật theo Nghị quyết 76/2025/UBTVQH15.

Có hỗ trợ chuyển đổi hàng loạt không?

Có! Bạn có thể upload file Excel/CSV hoặc paste danh sách địa chỉ để chuyển đổi hàng loạt.

{ "status": true, "message": "Chuyển đổi địa chỉ thành công.", "data": { "old_address": { "province_code": 1, "province_name": "Thành phố Hà Nội", "district_code": 1, "district_name": "Quận Ba Đình", "ward_code": 1, "ward_name": "Phường Phúc Xá" }, "new_addresses": [ { "province_code": 1, "province_name": "Thành phố Hà Nội", "ward_code": 101, "ward_name": "Phường Ba Đình" } ] } }

{ "status": true, "message": "Lấy thông tin địa chỉ mới thành công.", "data": { "province_code": 1, "province_name": "Thành phố Hà Nội", "ward_code": 256, "ward_name": "Phường Ba Đình" } }

{ "status": true, "message": "Xử lý file Excel thành công.", "data": [ { "index": 0, "status": true, "data": { "old_address": {}, "new_addresses": [] } } ] }