@0xd33p/vietnam-divisions

Dữ liệu hành chính Việt Nam — không phụ thuộc runtime nào.

Cung cấp cả hệ thống hiện tại (34 tỉnh, sau sáp nhập 2025) và cũ (63 tỉnh) kèm tự động tra cứu ID giữa hai hệ thống.

Cài đặt

npm install @0xd33p/vietnam-divisions

Bắt đầu nhanh

import { vn } from '@0xd33p/vietnam-divisions';

// Danh sách tỉnh hiện tại
const { data: tinh } = vn.divisions();

// Danh sách xã/phường theo tỉnh
const { data: xa } = vn.divisions('79'); // TP.HCM

// Tra cứu theo ID, mã, hoặc tên (tự động resolve ID cũ)
const tinhTra = vn.lookup('HCM');
const phuong = vn.lookup('00004');

// Tìm kiếm theo tên
const ketQua = vn.search('Hồ Chí Minh');

// Hệ thống cũ (63 tỉnh, 3 cấp)
const { data: tinhCu } = vn.legacy.divisions();
const { data: huyen } = vn.legacy.divisions('01');

API

vn.divisions(maTinh?)

| Đầu vào | Kết quả | | --------- | ----------------------- | | (không) | 34 tỉnh hiện tại | | "79" | Xã/phường thuộc tỉnh đó |

vn.lookup(truyVan)

Chấp nhận: ID tỉnh ("79"), mã tỉnh ("HCM"), ID xã ("00004"), hoặc tên đầy đủ.

Tự động resolve ID cũ sang ID mới.

vn.search(ten, maTinh?)

Tìm mờ theo tên (không phân biệt hoa thường). Có maTinh thì giới hạn trong tỉnh đó.

vn.addressLookup(diaChi)

Phân tích địa chỉ dạng chuỗi và trả về kết quả khớp ở cả hai hệ thống.

const ketQua = vn.addressLookup(
  'Thôn Nghĩa Thắng, Đông Hòa, TP Thái Bình, Thái Bình',
);
// {
//   legacy: { province: { id: '34', name: 'Tỉnh Thái Bình' }, ... },
//   v3:     { province: { id: '33', name: 'Hưng Yên' }, ... },
// }

Tính năng:

• Tự động tách thành phần (dấu phẩy, nhận diện cấp)
• Không phân biệt có dấu / không dấu ("Thai Binh" → "Thái Bình")
• Mở rộng viết tắt ("TP" → "Thành phố")
• Chế độ chặt: báo lỗi nếu thiếu hoặc không xác định được tỉnh

vn.legacy.*

3 phương thức tương tự (divisions, lookup, search) cho hệ thống 63 tỉnh cũ với 3 cấp (tỉnh → huyện → xã).

Kiểu dữ liệu

| Kiểu | Mô tả | | --------------------- | -------------------------------------------- | | GeoUnit | { id: string; name: string } | | GeoResult<T> | { data: T } — thành công | | GeoErrorResult | { data: null; error: GeoError } — thất bại | | GeoError | 11 mã lỗi dạng discriminated union | | AddressLookupResult | { legacy: {...}, v3: {...} } |

Dữ liệu

| Hệ thống | Tỉnh | Huyện | Xã | | ------------- | ---- | ----- | ------ | | v3 (hiện tại) | 34 | — | 3.321 | | Cũ | 63 | 696 | 10.051 |

Hệ thống v3 áp dụng theo Nghị quyết 202/2025/QH15 (sáp nhập tỉnh có hiệu lực từ 2025).

Ứng dụng

• Form địa chỉ — đổ dữ liệu tỉnh/xã vào dropdown
• Xác thực địa chỉ — kiểm tra địa chỉ nhập vào có hợp lệ không
• Chuyển đổi dữ liệu — map địa chỉ cũ sang hệ thống mới