quangtam / vietnam-address-database
Raw JSON database for Vietnamese administrative addresses according to Resolution 202/2025/QH15
Requires
- php: >=7.4
Requires (Dev)
- phpunit/phpunit: ^9.0
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
- Data Repository: DVHCVN Database
- Legal Documents: Administrative Reorganization Resolutions 2023-2025
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.