Vietnam Address Data 🇻🇳

Normalized Vietnamese administrative data — provinces & wards — with full TypeScript support and Vietnamese-aware search utilities.

Updated for the 2025 administrative restructuring (effective 01/07/2025), following the merger of administrative units under Resolution 1171/NQ-UBTVQH15.

✨ Features

• 📦 Normalized data — flat Province[] and Ward[] arrays, no nested structures
• 🔷 Full TypeScript support — types and .d.ts declarations included out of the box
• 🔍 Vietnamese-aware search — diacritic-insensitive partial matching ("hoan kiem" matches "Hoàn Kiếm")
• ⚡ Zero runtime dependencies — lightweight, pure data + utilities
• 🇻🇳 2025 data — reflects the latest administrative restructuring across all provinces

📦 Installation

npm install vietnam-address-data

yarn add vietnam-address-data

pnpm add vietnam-address-data

🚀 Usage

Import data

import { provinces, wards } from 'vietnam-address-data'

// All provinces
console.log(provinces)
// [
//   { id: "01", name: "Hà Nội" },
//   { id: "02", name: "Bắc Ninh" },
//   ...
// ]

// All wards
console.log(wards)
// [
//   { id: "10105001", name: "Phường Hoàn Kiếm", provinceId: "01" },
//   { id: "10105002", name: "Phường Cửa Nam",   provinceId: "01" },
//   ...
// ]

Search for wards

import { findWard } from 'vietnam-address-data'

// Works with Vietnamese diacritics
findWard("Hoàn Kiếm")
// => [{ id: "10105001", name: "Phường Hoàn Kiếm", provinceId: "01" }]

// Also works without diacritics (partial match)
findWard("hoan kiem")
// => [{ id: "10105001", name: "Phường Hoàn Kiếm", provinceId: "01" }]

// Partial match
findWard("ba dinh")
// => [{ id: "10101003", name: "Phường Ba Đình", provinceId: "01" }]

Search for provinces

import { findProvince } from 'vietnam-address-data'

findProvince("hà nội")
// => [{ id: "01", name: "Hà Nội" }]

findProvince("thanh")
// => provinces containing "thanh" (e.g. Thanh Hoá, Thanh Hóa, ...)

Get wards by province

import { getWardsByProvince } from 'vietnam-address-data'

const hanoiWards = getWardsByProvince("01")
// => all wards in Hà Nội

Normalize Vietnamese text

import { normalizeVietnamese } from 'vietnam-address-data'

normalizeVietnamese("Phường Hoàn Kiếm")
// => "phuong hoan kiem"

normalizeVietnamese("  Đà Nẵng  ")
// => "da nang"

TypeScript types

import type { Province, Ward } from 'vietnam-address-data'

const myProvince: Province = { id: "01", name: "Hà Nội" }

const myWard: Ward = {
  id: "10105001",
  name: "Phường Hoàn Kiếm",
  provinceId: "01"
}

📐 Data Schema

Province

| Field | Type | Description | |-------|--------|----------------------------------------| | id | string | 2-digit BNV province code, zero-padded | | name| string | Province name (Vietnamese, no prefix) |

Ward

| Field | Type | Description | |--------------|--------|-------------------------------------------| | id | string | 8-digit ward code, zero-padded | | name | string | Ward name (Vietnamese, with type prefix) | | provinceId | string | Parent province ID |

🔧 API Reference

findWard(keyword: string): Ward[]

Search wards by name. Case-insensitive, diacritic-insensitive, partial match.

findProvince(keyword: string): Province[]

Search provinces by name. Case-insensitive, diacritic-insensitive, partial match.

getWardsByProvince(provinceId: string): Ward[]

Return all wards belonging to a province.

normalizeVietnamese(text: string): string

Remove Vietnamese diacritics, lowercase, and trim. Useful for building your own search or comparison logic.

🗺️ Roadmap

• [ ] District-level data (quận/huyện) as an intermediate layer
• [ ] Lookup by old code (pre-2025 → post-2025 mapping)
• [ ] ESM build (dist/index.esm.js)
• [ ] CDN/browser-ready bundle
• [ ] Postal code mapping

📚 Data Source

• EasyInvoice.vn — 2025 ward list
• Resolution 1171/NQ-UBTVQH15 — Official restructuring resolution
• Province codes follow the BNV (Ministry of Home Affairs) standard

🤝 Contributing

Pull requests are welcome! If you find data inaccuracies or have suggestions, please open an issue.

📄 License

MIT © phucanhle