Registry / data / vietnam-address-database

vietnam-address-database

library1.0.0jsnpmunverified

This package provides a raw JSON database of Vietnamese administrative addresses, meticulously structured according to Resolution 202/2025/QH15 and NQ-UBTVQH15, with applicability from July 1, 2025, and January 1, 2025, respectively. As of version 1.0.0, it includes data for 34 provinces/cities, 3,321 wards/communes, and 10,977 ward mapping rules. It is explicitly designed as a dependency for other JavaScript/TypeScript libraries, offering unopinionated access to the latest administrative boundary data. The package ships with comprehensive TypeScript type definitions, enabling robust static type checking for consumers. Its core differentiator is providing a directly consumable, machine-readable dataset reflecting future administrative changes.

data serialization

npm install vietnam-address-database

github ↗package ↗

INSTALL

IMPORT

SIG · VIETNAM-ADDRESS-DA

vietnam-address-database

datajavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

addressData

✓ import addressData from 'vietnam-address-database';

✗ const addressData = require('vietnam-address-database');

This is the default export containing the entire database as an array of DatabaseItem. Both ESM and CJS are supported.

Province

✓ import type { Province } from 'vietnam-address-database';

Imports the TypeScript type definition for a Province object.

Ward

✓ import type { Ward } from 'vietnam-address-database';

Imports the TypeScript type definition for a Ward object.

WardMapping

✓ import type { WardMapping } from 'vietnam-address-database';

Imports the TypeScript type definition for a WardMapping object, used for old-to-new ward code transitions.

DatabaseItem

✓ import type { DatabaseItem } from 'vietnam-address-database';

Imports the overarching TypeScript type definition for items within the exported data array, which can be 'header', 'database', or 'table' types.

This quickstart demonstrates how to import the `vietnam-address-database` data, extract the specific 'provinces', 'wards', and 'ward_mappings' tables, and provides example functions for accessing and searching the administrative data with TypeScript types.

import addressData, { Province, Ward, WardMapping, DatabaseItem } from 'vietnam-address-database'; // The exported data is an array of DatabaseItem, which includes header, database info, and tables. const allData: DatabaseItem[] = addressData; // Extract specific tables for easier access and type safety let provinces: Province[] = []; let wards: Ward[] = []; let wardMappings: WardMapping[] = []; allData.forEach(item => { if (item.type === 'table') { if (item.name === 'provinces') { provinces = item.data as Province[]; } else if (item.name === 'wards') { wards = item.data as Ward[]; } else if (item.name === 'ward_mappings') { wardMappings = item.data as WardMapping[]; } } }); // Example functions to work with the extracted data function getProvinces(): Province[] { console.log(`Found ${provinces.length} provinces.`); return provinces; } function getProvinceByCode(code: string): Province | undefined { const province = provinces.find(p => p.province_code === code); console.log(`Province for code '${code}': ${province?.name || 'Not found'}`); return province; } // Usage examples: const haNoi = getProvinceByCode('01'); // Example: Hà Nội const firstWard = wards[0]; if (firstWard) { console.log(`First ward: ${firstWard.name}, code: ${firstWard.ward_code}`); } const firstMapping = wardMappings[0]; if (firstMapping) { console.log(`First ward mapping: Old: ${firstMapping.old_ward_name} (${firstMapping.old_ward_code}), New: ${firstMapping.new_ward_name} (${firstMapping.new_ward_code})`); }

Debug

Known issues

gotchaThe administrative data provided in this package is based on future resolutions (202/2025/QH15 and NQ-UBTVQH15) which apply from July 1, 2025, and January 1, 2025, respectively. This means the data may not reflect the *current* administrative boundaries prior to these dates.

fix

Be aware of the effective dates of the data. If you need current administrative data (prior to 2025), this package may not be suitable. Verify the 'created_at' and 'updated_at' fields for specific records if available, or consult official government sources for current data.

affects: >=1.0.0

gotchaThis package exports raw JSON data in a structured array. It does not provide utility functions for querying, indexing, or managing the data. Consumers must implement their own logic to parse the array and extract the desired tables (provinces, wards, ward_mappings).

fix

Implement custom parsing logic to iterate through the exported `addressData` array and extract the 'table' type items based on their 'name' property (e.g., 'provinces', 'wards'). Cast `item.data` to the appropriate TypeScript type (e.g., `Province[]`) for type safety.

affects: >=1.0.0

gotchaAs a new package (v1.0.0), while the data structure is clearly defined, future major versions might introduce schema changes to the raw JSON output to accommodate new government resolutions or improved data representation. Always consult release notes for breaking changes.

fix

Pin to exact major versions (`^1.0.0`) in your `package.json` and review changelogs carefully when upgrading major versions to anticipate potential schema changes in the raw data structure.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: addressData.find is not a function

The default export `addressData` is an array of `DatabaseItem`s (header, database info, tables), not a direct array of provinces or wards. You cannot directly call `.find()` on `addressData` to locate a province.

fix

First, iterate through `addressData` to extract the specific 'table' you need (e.g., `provinces`), then apply array methods like `.find()` to the extracted table: `const provinces = addressData.find(item => item.name === 'provinces')?.data as Province[]; provinces.find(...)`

Error: Cannot find module 'vietnam-address-database'

The package was not correctly installed or there's a typo in the import path.

fix

Ensure the package is installed: `npm install vietnam-address-database`. Double-check the import statement for typos: `import addressData from 'vietnam-address-database';` or `const addressData = require('vietnam-address-database');`

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/quangtam/vietnam-address-database ↗

packagehttps://www.npmjs.com/package/vietnam-address-database ↗