PkgFoundry
Catalog npm
Back to packageRELEASE DETAILS

0.3.0

npm

@0xd33p/vietnam-divisions

Vietnam administrative divisions — raw seed data + sync helpers (34 provinces, 3,321 communes, v3)

Published12 Jul 2026
Direct dependencies4
Transitive dependenciesNot calculated

README

Current package documentation

@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àoKế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ểuMô tả
GeoUnit{ id: string; name: string }
GeoResult<T>{ data: T } — thành công
GeoErrorResult{ data: null; error: GeoError } — thất bại
GeoError11 mã lỗi dạng discriminated union
AddressLookupResult{ legacy: {...}, v3: {...} }

Dữ liệu

Hệ thốngTỉnhHuyệnXã
v3 (hiện tại)34—3.321
Cũ6369610.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

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 4

Native requirements
4 direct targetsNot calculated transitive count
Package / targetRequirementRelationship
@vitest/coverage-v8
Environment
{
  "local_name": "@vitest/coverage-v8",
  "alias": false,
  "peer_metadata": null
}
catalog:development
tsx
Environment
{
  "local_name": "tsx",
  "alias": false,
  "peer_metadata": null
}
^4.22.4development
typescript
Environment
{
  "local_name": "typescript",
  "alias": false,
  "peer_metadata": null
}
catalog:development
vitest
Environment
{
  "local_name": "vitest",
  "alias": false,
  "peer_metadata": null
}
catalog:development

Distribution files

1 collected
Distribution 1

Source distribution

Source file
Checksums from source
{
  "integrity": "sha512-AxVI5IhAKgt0OyH1bFE/y6Uq05cDlQlgMuelvFx26J/8Hsst3G0KQjnJzqKo6stnYtxQYta6c5SOeUgaYEwIaQ==",
  "shasum": "7557efaa5a293ee66a676020d5ad77c42fbb436e",
  "tarball": "https://registry.npmjs.org/@0xd33p/vietnam-divisions/-/vietnam-divisions-0.3.0.tgz",
  "fileCount": 49,
  "unpackedSize": 4781720,
  "signatures": [
    {
      "keyid": "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U",
      "sig": "MEUCIB9cCjFUSTGjQENgHc5gsjPfTSnL76BAOi+iZtoIZfuuAiEAjDQTTfoo99+WbWpyC0YKk1jkohNKVRq7TXqOA7HrdDY="
    }
  ]
}

Metadata history

Meaningful changes
Current collected state Current

Observed since 20 Oct, 23:04 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package_version:8f271d3d673a89d0121ea632c20ff7bc27243d8a123ac9cafea34783c43f0f4e

Other collected versions

0.2.012 JulView all collected versions →