Vietnam Administrative Address Database

Common errors

• TypeError: addressData.find is not a function

  cause 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'

  cause 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');`

Warnings

• gotcha The 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.
• gotcha This 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.
• gotcha As 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.

Install

• npm install vietnam-address-database npm
• yarn add vietnam-address-database yarn
• pnpm add vietnam-address-database pnpm

Imports

• addressData
  wrong:

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

  correct:

  import addressData from '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.

Quickstart

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})`);
}