quangtam/vietnam-address-database

Raw JSON database for Vietnamese administrative addresses according to Resolution 202/2025/QH15

v1.0.0 2025-07-15 16:48 UTC

This package is auto-updated.

Last update: 2025-07-15 17:40:52 UTC


README

Raw JSON database for Vietnamese administrative addresses according to Resolution 202/2025/QH15.

This repository provides the same database for both JavaScript/TypeScript and PHP platforms.

Version 1.0.0 - First Release

34 Tỉnh/Thành phố (Provinces/Cities)
3,321 Phường/Xã (Wards/Communes)
10,977 quy tắc mapping (Mapping rules)

Data Sources

This database integrates data from two major administrative updates:

  • Resolution 202/2025/QH15 (effective from July 1, 2025)
  • Resolution NQ-UBTVQH15 (effective from January 1, 2025)

Quick Start

JavaScript/TypeScript

npm install vietnam-address-database
const addressData = require('vietnam-address-database');
console.log(addressData[0].version); // "1.1"

PHP

composer require quangtam/vietnam-address-database
use VietnamAddressDatabase\VietnamAddressDatabase;
$provinces = VietnamAddressDatabase::getProvinces();

Database Statistics

  • 34 Tỉnh/Thành phố (Provinces/Cities)
  • 3,321 Phường/Xã (Wards/Communes)
  • 10,977 quy tắc mapping (ánh xạ mã cũ sang mới)

Administrative Updates Integration

This database reflects the latest Vietnamese administrative changes from:

  • Resolution 202/2025/QH15 (effective July 1, 2025)
  • Resolution NQ-UBTVQH15 (effective January 1, 2025)

Platform-Specific Documentation

Publishing

See PUBLISHING.md for detailed publishing instructions for both platforms.

Data Source

This database is based on Resolution 202/2025/QH15 and contains the most up-to-date Vietnamese administrative addresses.

Primary Sources

Legal Framework

The database integrates administrative changes from:

  • Resolution 202/2025/QH15 (effective July 1, 2025)
  • Resolution NQ-UBTVQH15 (effective January 1, 2025)
  • Comprehensive administrative reorganization resolutions for 63 provinces/cities (2023-2025)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.