API Documentation
REST API cho dữ liệu đơn vị hành chính Việt Nam v2.1
LiveREST APIJSON ResponseVersion 2.1
Tổng quan & Hướng dẫn sử dụng

Bộ dữ liệu cung cấp thông tin đầy đủ về các đơn vị hành chính Việt Nam sau sáp nhập, gồm 34 tỉnh/thành phố và 3,321 phường/xã/thị trấn. Dữ liệu liên kết qua province_code.

  • API trả về dữ liệu chuẩn REST, hỗ trợ tìm kiếm, phân trang, lọc, chuyển đổi địa chỉ, thống kê.
  • Các file JSON có thể tải trực tiếp ở mục Tải dữ liệu.
  • Tham khảo Schema TypeScript Bảng trường dữ liệu bên dưới để tích hợp.
Quick Start

Base URL:

https://your-domain.com/api

Example Request:

curl https://your-domain.com/api/administrative-units?limit=5
Tải dữ liệu JSON
Download trực tiếp các file dữ liệu JSON

Tỉnh/Thành phố (Mới)

34 records10KB

Phường/Xã (Mới)

3,321 records601KB

API Endpoints
Danh sách tất cả endpoints có sẵn với mô tả chi tiết
Administrative Units
Lấy danh sách đơn vị hành chính với tìm kiếm và phân trang
GET

Endpoint:

GET /api/administrative-units
Provinces List
Lấy danh sách tất cả tỉnh/thành phố với thống kê
GET

Endpoint:

GET /api/provinces
Province Detail
Lấy thông tin chi tiết của một tỉnh/thành phố
GET

Endpoint:

GET /api/provinces/[name]
Address Conversion
Chuyển đổi địa chỉ cũ sang mới
GET/POST

Endpoint:

GET/POST /api/convert
Statistics
Lấy thống kê tổng quan của dữ liệu
GET

Endpoint:

GET /api/stats
Chi tiết files dữ liệu
Thông tin đầy đủ về các file JSON có thể tải xuống
Tỉnh/Thành phố (Mới)
34 tỉnh/thành phố sau sáp nhập với thông tin chi tiết
File:

thanh_pho_new.json

Size:

10KB

Records:

34 records

Type:

JSON

Phường/Xã (Mới)
3,321 phường/xã/thị trấn sau sáp nhập
File:

phuong_xa_new.json

Size:

601KB

Records:

3,321 records

Type:

JSON

Tỉnh/Thành phố (Cũ)
Dữ liệu tỉnh/thành phố trước khi sáp nhập
File:

old/province_old.json

Size:

5.1KB

Records:

63 records

Type:

JSON

Quận/Huyện (Cũ)
Dữ liệu quận/huyện trước khi sáp nhập
File:

old/district_old.json

Size:

77KB

Records:

705 records

Type:

JSON

Phường/Xã (Cũ)
Dữ liệu phường/xã trước khi sáp nhập
File:

old/commune_old.json

Size:

1.1MB

Records:

10,599 records

Type:

JSON

Schema TypeScript
Định nghĩa kiểu dữ liệu Province Ward dùng cho toàn bộ API

export interface Province {
    province_code: string;
    name: string;
    code: string;
    short_name: string;
    place_type: "Thành phố Trung Ương" | "Tỉnh";
    province_merge: {
        is_merged: boolean;
        merged_with: string[];
        administrative_center: string | null;
    };
    chairman: string | null;
    place_numbers: number[];
    area_km2: number | null;
    population: number | null;
    grdp_million_vnd: number | null;
    borders: string[];
}

export interface Ward {
    province_code: string;
    ward_code: string;
    name: string;
    ward_old: string;
}
Bảng trường dữ liệu chính
Mô tả chi tiết các trường trong ProvinceWard
TrườngKiểuMô tảVí dụ
province_codestringMã tỉnh/thành phố duy nhất"01", "79"
namestringTên chính thức đầy đủ"Hà Nội"
codestringMã viết tắt 3 ký tự"HNI", "HCM"
short_namestringTên ngắn gọn"Hà Nội"
place_typestringLoại đơn vị"Thành phố Trung Ương", "Tỉnh"
province_merge.is_mergedbooleanTrạng thái sáp nhậptrue, false
province_merge.merged_withstring[]Tỉnh sáp nhập cùng["Hà Giang"]
province_merge.administrative_centerstring | nullTrung tâm hành chính"Tuyên Quang"
chairmanstring | nullChủ tịch UBND"Nguyễn Văn Được"
place_numbersnumber[]Mã biển số xe[29, 30, 31, 32, 33, 40]
area_km2number | nullDiện tích (km²)6772.59
populationnumber | nullDân số14002598
grdp_million_vndnumber | nullGRDP (triệu VNĐ)2715782233
bordersstring[]Biên giới liền kề["Đồng Nai", "Biển Đông"]
TrườngKiểuMô tảVí dụ
province_codestringMã tỉnh (foreign key)"01", "79"
ward_codestringMã phường/xã duy nhất"00070", "27316"
namestringTên đầy đủ (có prefix)"Phường Hoàn Kiếm"
ward_oldstringPhường/xã được sáp nhập"Phường 5, Phường 7, Phường 9 (Quận 5)"
Error Handling
Cách xử lý lỗi và HTTP status codes
400Bad Request - Parameters không hợp lệ
404Not Found - Không tìm thấy dữ liệu
500Internal Server Error - Lỗi server

Error Response Format:

{
  "success": false,
  "error": "Error message description"
}