Tỉnh thành & phường xã Việt Nam API

Đủ 34 tỉnh thành và 3.321 phường / xã / đặc khu sau sắp xếp 07/2025, kèm mã, mã bưu chính, tìm kiếm và chuyển đổi đơn vị cũ → mới.

GEThttps://apibox.io.vn/v1/vn-provinces

Dữ liệu & JSON▶ Dùng thử online

Từ 1/7/2025, Việt Nam có 34 tỉnh, thành phố và không còn cấp huyện: mỗi tỉnh chia trực tiếp thành phường, xã và đặc khu. API này trả về đúng cấu trúc đó với mã đơn vị hành chính chính thức của Tổng cục (nay là Cục) Thống kê, tên tiếng Việt và tiếng Anh, loại đơn vị và mã bưu chính, sẵn sàng cho form địa chỉ và kiểm tra địa chỉ. Các thay đổi sau đó (ví dụ xã lên phường năm 2026) đã được cập nhật; phản hồi luôn ghi phiên bản dữ liệu và nghị quyết mới nhất đã áp dụng.

GET /v1/vn-provinces liệt kê các tỉnh kèm số đơn vị trực thuộc và nguồn gốc sáp nhập; /v1/vn-provinces/{mã} (hoặc tên như hcm, Hà Nội) trả về một tỉnh cùng toàn bộ phường xã, lọc được bằng type=ward|commune|special_zone. /v1/vn-provinces/wards/{mã} trả về một đơn vị kèm danh sách phường/xã trước 2025 đã hợp thành, có cả huyện và tỉnh cũ.

Để chuyển địa chỉ cũ, old_ward={mã cũ} cho biết phường/xã cũ đã vào đơn vị mới nào (một số bị chia cho nhiều nơi), còn q= tìm theo tên không cần dấu (q=thu dau mot). Nếu tên không còn tồn tại, API tìm thêm trong tên cũ và cho biết đơn vị mới tương ứng. Dữ liệu lấy từ bảng chuyển đổi của Cục Thống kê và bộ dữ liệu mở github.com/ThangLeQuoc/vietnamese-provinces-database (MIT), được cập nhật khi có nghị quyết mới.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mặc định
`code`	path	string	không		`/v1/vn-provinces/{mã}`: mã tỉnh 2 số hoặc tên (`79`, `hcm`, `Hà Nội`). Tên khác: tham số `province`.
`ward`	query	string	không		Mã phường/xã (5 số), giống `/v1/vn-provinces/wards/{mã}`.
`q`	query	string	không		Tìm tỉnh, phường xã theo tên, có dấu hoặc không. Kết hợp `province` và `limit` (tối đa 100).
`match_old`	query	boolean	không	`false`	Dùng với `q`: tìm cả tên trước 2025 (luôn tìm khi không có kết quả hiện hành).
`old_ward`	query	string	không		Mã phường/xã trước 2025 → đơn vị mới mà nó thuộc về.
`type`	query	string	không		Lọc phường xã của một tỉnh: `ward`, `commune` hoặc `special_zone`.
`formed_from`	query	boolean	không	`false`	Kèm danh sách đơn vị cũ hợp thành cho mỗi phường xã trong danh sách và kết quả tìm kiếm.

Ví dụ

curl "https://apibox.io.vn/v1/vn-provinces?old_ward=00013" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-provinces?old_ward=00013', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/vn-provinces?old_ward=00013",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-provinces?old_ward=00013');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "version": "v5.2.0",
  "decree": "388/NQ-UBTVQH16",
  "updated": "2026-09-20",
  "old": {
    "code": "00013",
    "name": "Phường Quán Thánh",
    "change": "Nhập toàn bộ",
    "district": "Quận Ba Đình",
    "district_code": "001",
    "province": "Thành phố Hà Nội",
    "province_code": "01"
  },
  "split": false,
  "new": [
    {
      "code": "00004",
      "name": "Ba Đình",
      "full_name": "Phường Ba Đình",
      "name_en": "Ba Dinh",
      "type": "Phường",
      "type_en": "ward",
      "slug": "ba_dinh",
      "postal_code": "11120",
      "province_code": "01",
      "province": "Hà Nội",
      "change": "Nhập toàn bộ"
    }
  ]
}

Ứng dụng

Dropdown chọn tỉnh → phường xã trong form đặt hàng, đăng ký
Chuyển địa chỉ khách hàng từ cấu trúc 3 cấp cũ sang 2 cấp mới
Kiểm tra, chuẩn hoá địa chỉ giao hàng trước khi gửi đơn vị vận chuyển
Thống kê, vẽ bản đồ theo tỉnh thành mới

Hỏi đáp

Chuyển địa chỉ cũ sang mới thế nào?

Nếu có mã phường/xã cũ, gọi ?old_ward=00013: phản hồi cho biết đơn vị mới (Phường Ba Đình với Phường Quán Thánh cũ). Nếu chỉ có tên, gọi ?q=Quán Thánh&match_old=true và lọc thêm theo province.

Dữ liệu cập nhật đến khi nào?

Theo danh mục chính thức sau 1/7/2025 và các nghị quyết của Ủy ban Thường vụ Quốc hội sau đó; mọi phản hồi đều có version, decree (nghị quyết mới nhất đã áp dụng) và updated. Chúng tôi dựng lại dữ liệu khi nguồn có thay đổi.

Vì sao không có quận/huyện?

Cấp huyện (quận, huyện, thị xã) đã bỏ từ 1/7/2025. Tên và mã quận/huyện cũ vẫn có trong formed_from để hỗ trợ chuyển đổi.

API liên quan

{✓}

Tỉnh thành & phường xã Việt Nam API

Tham số

Ví dụ

Kết quả trả về

Ứng dụng

Hỏi đáp

API liên quan

Kiểm tra JSON

Định dạng JSON

CSV sang JSON