{"id":16572,"library":"vietnam-address-database","title":"Vietnam Administrative Address Database","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/quangtam/vietnam-address-database","tags":["javascript","vietnam","address","database","provinces","districts","wards","administrative","vietnamese","typescript"],"install":[{"cmd":"npm install vietnam-address-database","lang":"bash","label":"npm"},{"cmd":"yarn add vietnam-address-database","lang":"bash","label":"yarn"},{"cmd":"pnpm add vietnam-address-database","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the default export containing the entire database as an array of DatabaseItem. Both ESM and CJS are supported.","wrong":"const addressData = require('vietnam-address-database');","symbol":"addressData","correct":"import addressData from 'vietnam-address-database';"},{"note":"Imports the TypeScript type definition for a Province object.","symbol":"Province","correct":"import type { Province } from 'vietnam-address-database';"},{"note":"Imports the TypeScript type definition for a Ward object.","symbol":"Ward","correct":"import type { Ward } from 'vietnam-address-database';"},{"note":"Imports the TypeScript type definition for a WardMapping object, used for old-to-new ward code transitions.","symbol":"WardMapping","correct":"import type { WardMapping } from 'vietnam-address-database';"},{"note":"Imports the overarching TypeScript type definition for items within the exported data array, which can be 'header', 'database', or 'table' types.","symbol":"DatabaseItem","correct":"import type { DatabaseItem } from 'vietnam-address-database';"}],"quickstart":{"code":"import addressData, { Province, Ward, WardMapping, DatabaseItem } from 'vietnam-address-database';\n\n// The exported data is an array of DatabaseItem, which includes header, database info, and tables.\nconst allData: DatabaseItem[] = addressData;\n\n// Extract specific tables for easier access and type safety\nlet provinces: Province[] = [];\nlet wards: Ward[] = [];\nlet wardMappings: WardMapping[] = [];\n\nallData.forEach(item => {\n  if (item.type === 'table') {\n    if (item.name === 'provinces') {\n      provinces = item.data as Province[];\n    } else if (item.name === 'wards') {\n      wards = item.data as Ward[];\n    } else if (item.name === 'ward_mappings') {\n      wardMappings = item.data as WardMapping[];\n    }\n  }\n});\n\n// Example functions to work with the extracted data\nfunction getProvinces(): Province[] {\n  console.log(`Found ${provinces.length} provinces.`);\n  return provinces;\n}\n\nfunction getProvinceByCode(code: string): Province | undefined {\n  const province = provinces.find(p => p.province_code === code);\n  console.log(`Province for code '${code}': ${province?.name || 'Not found'}`);\n  return province;\n}\n\n// Usage examples:\nconst haNoi = getProvinceByCode('01'); // Example: Hà Nội\nconst firstWard = wards[0];\nif (firstWard) {\n  console.log(`First ward: ${firstWard.name}, code: ${firstWard.ward_code}`);\n}\n\nconst firstMapping = wardMappings[0];\nif (firstMapping) {\n  console.log(`First ward mapping: Old: ${firstMapping.old_ward_name} (${firstMapping.old_ward_code}), New: ${firstMapping.new_ward_name} (${firstMapping.new_ward_code})`);\n}\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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(...)`","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.","error":"TypeError: addressData.find is not a function"},{"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');`","cause":"The package was not correctly installed or there's a typo in the import path.","error":"Error: Cannot find module 'vietnam-address-database'"}],"ecosystem":"npm"}