vn-province

Dữ liệu static 34 tỉnh/thành phố và 3.321 phường/xã/đặc khu của Việt Nam (đơn vị hành chính 2 cấp), mỗi ward đã được nest sẵn vào wards[] của province.

Không gọi network lúc runtime, không dependency. Có sẵn ESM + CJS + TypeScript types.

Cài đặt

npm install vn-province

Sử dụng

import {
    provinces,
    wards,
    getProvinces,
    getProvinceByCode,
    getWardsByProvinceCode,
    getWardByCode,
} from "vn-province";

getProvinces().length; // 34
getProvinceByCode(79); // { name: "Thành phố Hồ Chí Minh", code: 79, ... }
getWardsByProvinceCode(79).length; // 168
getWardByCode(4); // { name: "Phường Ba Đình", code: 4, province_code: 1, ... }

// Dropdown tỉnh -> ward
const provinceOptions = provinces.map((p) => ({
    value: p.code,
    label: p.name,
}));
const wardOptions = getWardsByProvinceCode(1).map((w) => ({
    value: w.code,
    label: w.name,
}));

CommonJS:

const { provinces, getWardsByProvinceCode } = require("vn-province");

API

| Export | Kiểu | Mô tả | | ------------------------------ | ----------------------- | -------------------------------------------------- | | provinces | Province[] | Toàn bộ province, kèm wards | | wards | Ward[] | Toàn bộ ward cả nước (flatten) | | getProvinces() | Province[] | Như provinces | | getProvinceByCode(code) | Province \| undefined | Tra province theo code | | getWardsByProvinceCode(code) | Ward[] | Ward của một province, [] nếu code không tồn tại | | getWardByCode(code) | Ward \| undefined | Tra ward theo code (code ward duy nhất toàn quốc) |

interface Province {
    name: string;
    code: number;
    division_type: "thành phố trung ương" | "tỉnh";
    codename: string;
    phone_code: number;
    wards: Ward[];
}

interface Ward {
    name: string;
    code: number;
    division_type: "phường" | "xã" | "đặc khu";
    codename: string;
    province_code: number;
}

Các mảng trả về là chính object dữ liệu gốc (không copy) — đừng mutate; cần sort/filter thì [...provinces] trước.

Cập nhật dữ liệu

npm run generate   # fetch lại từ provinces.open-api.vn -> src/data.json
npm run build
npm test

Nguồn: provinces.open-api.vn (/api/v2/p/ và /api/v2/w/).

Publish

npm publish --access public

License

MIT