API tỉnh thành Việt Nam miễn phí (JSON): 34 tỉnh, 3.321 xã, phường, đặc khu

Endpoint

URL gốc:

Phương thức GET, phản hồi application/json, mã hoá UTF-8. Dung lượng là file chưa nén; máy chủ nén gzip khi trình duyệt hỗ trợ.

Định dạng phản hồi

Mọi endpoint (trừ meta.json) trả cùng một dạng: nguon (trang dữ liệu mở), giay_phep, ngay (ngày dựng), du_lieu_den (văn bản có hiệu lực đến ngày), cot (danh sách cột) và dong (mảng đối tượng, mỗi đối tượng một dòng).

Ví dụ /api/v1/xa/ha-noi.json (rút gọn):

{
    "nguon": "https://diachiviet.com/du-lieu-mo/",
    "giay_phep": "CC BY 4.0",
    "ngay": "2026-11-05",
    "du_lieu_den": "20/09/2026",
    "cot": [
        "ma_xa",
        "ten",
        "loai",
        "ma_tinh",
        "ten_tinh",
        "ma_buu_chinh",
        "dien_tich_km2",
        "quy_mo_dan_so",
        "nghi_quyet",
        "url"
    ],
    "dong": [
        {
            "ma_xa": "00004",
            "ten": "Phường Ba Đình",
            "loai": "Phường",
            "ma_tinh": "01",
            "ten_tinh": "Thành phố Hà Nội",
            "ma_buu_chinh": "11120",
            "dien_tich_km2": 2.97,
            "quy_mo_dan_so": 65023,
            "nghi_quyet": "Nghị quyết số 1656/NQ-UBTVQH15",
            "url": "https://diachiviet.com/hanh-chinh/ha-noi/phuong-ba-dinh/"
        },
        …
    ]
}

Slug 34 tỉnh, thành

Slug dùng trong xa/{slug-tinh}.json và xa-cu-moi/{slug-tinh}.json, trùng với đoạn cuối của cột url trong tinh.json (ví dụ https://diachiviet.com/hanh-chinh/ha-noi/).

Các cột dữ liệu

tinh.json

ma_tinh

Mã tỉnh 2 chữ số theo Quyết định 19/2025/QĐ-TTg (chuỗi, giữ số 0 ở đầu).

ten

Tên đơn vị.

ten_day_du

Tên đầy đủ, có "Tỉnh" hoặc "Thành phố".

loai

Bảng tỉnh: Tỉnh hoặc Thành phố. Bảng xã: Xã, Phường hoặc Đặc khu.

so_don_vi_cap_xa

Số đơn vị cấp xã của tỉnh.

url

Trang tra cứu tương ứng trên Địa Chỉ Việt.

xa.json, xa/{slug-tinh}.json

ma_xa

Mã xã 5 chữ số theo Quyết định 19/2025/QĐ-TTg (chuỗi, giữ số 0 ở đầu, ví dụ "00004").

ten

Tên đơn vị.

loai

Bảng tỉnh: Tỉnh hoặc Thành phố. Bảng xã: Xã, Phường hoặc Đặc khu.

ma_tinh

Mã tỉnh 2 chữ số theo Quyết định 19/2025/QĐ-TTg (chuỗi, giữ số 0 ở đầu).

ten_tinh

Tên đầy đủ của tỉnh, thành phố.

ma_buu_chinh

Mã bưu chính 5 số theo Quyết định 2334/QĐ-BKHCN.

dien_tich_km2

Diện tích (km²) ghi trong nghị quyết sắp xếp năm 2025. Ô trống: chưa có số liệu.

quy_mo_dan_so

Quy mô dân số ghi trong nghị quyết sắp xếp năm 2025; số liệu của đề án, không phải số điều tra dân số. Ô trống: chưa có số liệu.

nghi_quyet

Nghị quyết căn cứ thành lập đơn vị (năm 2025).

url

Trang tra cứu tương ứng trên Địa Chỉ Việt.

xa-cu-moi.json, xa-cu-moi/{slug-tinh}.json

ma_xa_cu

Mã đơn vị cấp xã trước 01/07/2025, danh mục bản 01/03/2025. Trống khi chưa xác định chắc chắn.

ten_xa_cu

Tên đơn vị cấp xã trước 01/07/2025, theo nghị quyết sắp xếp năm 2025.

quan_huyen_cu

Quận, huyện cũ. Trống khi chưa xác định chắc chắn.

tinh_cu

Tỉnh, thành cũ.

ma_xa_moi

Mã xã mới.

ten_xa_moi

Tên xã mới.

ma_tinh

Mã tỉnh 2 chữ số theo Quyết định 19/2025/QĐ-TTg (chuỗi, giữ số 0 ở đầu).

ten_tinh

Tên đầy đủ của tỉnh, thành phố.

pham_vi

"toàn bộ" hoặc ghi chú như "một phần", "phần còn lại". Đơn vị cũ bị chia cho nhiều đơn vị mới thì có nhiều dòng.

ten_danh_muc_cu

Tên trong danh mục bản 01/03/2025 khi khác cột ten_xa_cu (cách viết khác), dùng để đối chiếu, tìm kiếm. Trống khi giống nhau hoặc chưa xác định.

Ô trống là chuỗi rỗng ""; dien_tich_km2, quy_mo_dan_so là số khi có số liệu. Các cột mã (ma_tinh, ma_xa, ma_buu_chinh, ma_xa_cu, ma_xa_moi) là chuỗi.

Ví dụ code

JavaScript: chọn tỉnh rồi chọn xã, phường

Dán vào một file HTML và mở bằng trình duyệt; mỗi lần đổi tỉnh chỉ tải file của tỉnh đó (vài chục KB).

<select id="tinh"><option value="">Chọn tỉnh, thành</option></select>
<select id="xa" disabled><option value="">Chọn xã, phường</option></select>
<script>
const API = 'https://diachiviet.com/api/v1/';
const tinh = document.getElementById('tinh'), xa = document.getElementById('xa');

fetch(API + 'tinh.json').then(r => r.json()).then(d => {
  d.dong.forEach(t => {
    const slug = new URL(t.url).pathname.split('/')[2]; // ha-noi, ho-chi-minh...
    tinh.add(new Option(t.ten, slug));
  });
});

tinh.addEventListener('change', () => {
  xa.length = 1; xa.disabled = true;
  if (!tinh.value) return;
  fetch(API + 'xa/' + tinh.value + '.json').then(r => r.json()).then(d => {
    d.dong.forEach(x => xa.add(new Option(x.ten, x.ma_xa)));
    xa.disabled = false;
  });
});
</script>

Python (requests)

import requests

API = "https://diachiviet.com/api/v1/"
tinh = requests.get(API + "tinh.json", timeout=30).json()["dong"]
xa = requests.get(API + "xa/ha-noi.json", timeout=30).json()["dong"]
print(len(tinh), "tỉnh, thành;", len(xa), "xã, phường của Hà Nội")
for x in xa[:5]:
    print(x["ma_xa"], x["ten"], x["ma_buu_chinh"])

# Đơn vị cũ -> mới (một đơn vị cũ có thể có nhiều dòng)
for r in requests.get(API + "xa-cu-moi/ha-noi.json", timeout=30).json()["dong"]:
    if r["ten_xa_cu"] == "Phường Phúc Xá":
        print(r["ten_xa_cu"], r["quan_huyen_cu"], "->", r["ten_xa_moi"], r["pham_vi"])

curl, jq

curl -s https://diachiviet.com/api/v1/tinh.json | jq -r '.dong[] | [.ma_tinh, .ten] | @tsv'
curl -s https://diachiviet.com/api/v1/xa/ho-chi-minh.json | jq '.dong[] | {ma_xa, ten, ma_buu_chinh}'
curl -s https://diachiviet.com/api/v1/meta.json | jq '{built, law_date}'

Lưu ý khi dùng

• Nối bằng mã, không nối bằng tên: có nhiều xã, phường trùng tên ở các tỉnh khác nhau. Dùng ma_xa, ma_tinh làm khoá.
• Mã là chuỗi: giữ nguyên số 0 ở đầu ("00004", "01"); đừng ép sang số.
• Nên cache phía bạn: dữ liệu chỉ đổi khi có nghị quyết mới. Lưu bản sao trong ứng dụng hoặc cơ sở dữ liệu, kiểm tra meta.json (trường built) định kỳ, ví dụ mỗi ngày một lần, để biết khi nào cần tải lại.
• Không cam kết SLA: đây là dịch vụ miễn phí trên máy chủ của một trang web nhỏ, có thể tạm gián đoạn. Ứng dụng quan trọng nên tự lưu dữ liệu.
• Cần tải số lượng lớn hoặc dùng trong quy trình dựng (build): tải file ở trang dữ liệu mở hoặc kho GitHub, Hugging Face thay vì gọi API liên tục.
• Báo lỗi dữ liệu: qua trang Liên hệ.

Giấy phép và ghi nguồn

Dữ liệu cấp phép CC BY 4.0: dùng tự do, kể cả mục đích thương mại, với điều kiện ghi nguồn ở nơi người dùng thấy được (trang giới thiệu, chân trang, README của dự án). Mẫu ghi nguồn:

Nguồn gốc dữ liệu, mô tả chi tiết và file CSV: Dữ liệu mở đơn vị hành chính. Cũng có trên GitHub và Hugging Face. Cần đổi địa chỉ cũ sang mới mà không lập trình? Dùng công cụ đổi địa chỉ cũ sang mới.