vietnam-address-converter

v1.1.0

Published

a year ago

Thư viện JavaScript/TypeScript để tự động chuyển đổi địa chỉ hành chính Việt Nam từ cũ sang mới theo Nghị quyết 202/2025/QH15

Downloads

113

Vietnam Address Converter

Thư v## 📦 Cài đặt

npm install vietnam-address-converter

Lưu ý:
Thư viện sử dụng vietnam-address-database để cung cấp dữ liệu mapping, đảm bảo dữ liệu luôn cập nhật và đồng bộ.
Trong browser, dữ liệu được load từ CDN của vietnam-address-database để đảm bảo phiên bản mới nhất.avaScript/TypeScript để tự động chuyển đổi địa chỉ hành chính Việt Nam từ cũ sang mới theo Nghị quyết số 202/2025/QH15 của Quốc hội.

📦 NPM Package | 📚 Quick Start | 🌐 Live Demo | 🟦 PHP Version

✨ Tính năng chính

🔄 Chuyển đổi địa chỉ tự động: Chuyển đổi địa chỉ cũ sang địa chỉ mới theo quy định mới nhất
📊 Dữ liệu mapping thực tế: Sử dụng dữ liệu mapping chính thức từ cơ sở dữ liệu hành chính
🚀 Hiệu suất cao: ~1ms/địa chỉ, 956 địa chỉ/giây với data indexing tối ưu
🎯 Cấu trúc hành chính mới: Loại bỏ cấp quận/huyện theo Nghị quyết 202/2025/QH15
🔍 Tìm kiếm thông minh: Sử dụng fuzzy matching để tìm địa chỉ tương đồng
📱 Đa nền tảng: Hoạt động trên Node.js và trình duyệt
⚡ Hoạt động offline: Dữ liệu được tích hợp sẵn trong thư viện, không cần kết nối Internet

📈 Performance

| Metric | Value | |--------|--------| | Tốc độ chuyển đổi | ~0.967ms per address | | Throughput | 1034 addresses/second | | Initialization | ~20ms | | Success rate | 100% | | Memory usage | Optimized với caching |

👉 Xem chi tiết Performance Guide

Cài đặt

npm install vietnam-address-converter

🚀 Sử dụng cơ bản

1. Node.js Environment

import { VietnamAddressConverter } from 'vietnam-address-converter';

// Khởi tạo converter
const converter = new VietnamAddressConverter();
await converter.initialize();

// Chuyển đổi địa chỉ từ string
const result = converter.convertAddress('Phường 12, Quận Gò Vấp, Thành phố Hồ Chí Minh');

if (result.success) {
  console.log('Địa chỉ cũ:', result.originalAddress);
  console.log('Địa chỉ mới:', result.convertedAddress);
  console.log('Loại chuyển đổi:', result.mappingInfo?.mappingType);
} else {
  console.log('Lỗi:', result.message);
}

2. Browser Environment

🌐 Try Live Demo - Trải nghiệm trực tiếp trên trình duyệt

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/vietnam-address-converter@latest/dist/index.browser.js"></script>
</head>
<body>
  <script>
    async function convertAddress() {
      // Khởi tạo converter
      const converter = new VietnamAddressConverter.VietnamAddressConverter();
      
      // Load dữ liệu từ CDN của vietnam-address-database
      await converter.initializeFromUrl('https://unpkg.com/vietnam-address-database@latest/address.json');
      
      // Chuyển đổi địa chỉ
      const result = converter.convertAddress('Phường 12, Quận Gò Vấp, Thành phố Hồ Chí Minh');
      console.log(result);
    }
    
    convertAddress();
  </script>
</body>
</html>

3. ES Modules trong Browser

import { VietnamAddressConverter } from 'https://unpkg.com/vietnam-address-converter@latest/dist/index.esm.js';

const converter = new VietnamAddressConverter();
// Load data từ CDN của vietnam-address-database
await converter.initializeFromUrl('https://unpkg.com/vietnam-address-database@latest/address.json');

const result = converter.convertAddress('Phường 12, Quận Gò Vấp, TP.HCM');

4. Chuyển đổi từ object

// Địa chỉ cũ (có Quận/Huyện)
const addressObject = {
  ward: 'Phường 12',
  district: 'Quận Gò Vấp',  // Input có thể có district
  province: 'Thành phố Hồ Chí Minh',
  street: '123 Nguyễn Văn Cừ'
};

const result = converter.convertAddress(addressObject);

// Kết quả trả về (không có district theo cấu trúc mới)
// {
//   ward: 'Phường An Hội Tây',
//   province: 'Thành phố Hồ Chí Minh',
//   street: '123 Nguyễn Văn Cừ'
// }

📚 API Reference

VietnamAddressConverter

Khởi tạo

Node.js:

const converter = new VietnamAddressConverter();
await converter.initialize(); // Sử dụng dữ liệu mặc định

// Hoặc sử dụng file dữ liệu tùy chỉnh
await converter.initialize('/path/to/custom/data.json');

Browser:

const converter = new VietnamAddressConverter();
await converter.initializeFromUrl(); // Sử dụng default: vietnam-address-database CDN

// Hoặc sử dụng URL tùy chỉnh
await converter.initializeFromUrl('/path/to/custom/data.json');

convertAddress(address)

Chuyển đổi địa chỉ từ định dạng cũ sang mới.

Tham số:

address: string | FullAddress - Địa chỉ cần chuyển đổi

Kết quả trả về:

interface ConversionResult {
  success: boolean;
  originalAddress: FullAddress;
  convertedAddress?: NewAddress;  // Không có district
  mappingInfo?: {
    oldWardCode?: string;
    newWardCode?: string;
    mappingType: 'exact' | 'merged' | 'renamed' | 'unchanged' | 'not_found';
  };
  message?: string;
}

Các phương thức khác

// Lấy thống kê dữ liệu
const stats = converter.getDataStats();
// { provinces: 34, wards: 3321, mappings: 10039 }

// Lấy danh sách tỉnh/thành phố
const provinces = converter.getProvinces();

// Lấy danh sách phường/xã theo tỉnh
const wards = converter.getWardsByProvince('01'); // Mã tỉnh Hà Nội

// Tìm kiếm mapping theo từ khóa
const mappings = converter.searchMappings('Gò Vấp');

🔄 Các loại chuyển đổi

1. Merged (Gộp)

Nhiều phường/xã cũ được gộp thành một phường/xã mới:

// Phường 12 và Phường 14 → Phường An Hội Tây
converter.convertAddress('Phường 12, Quận Gò Vấp, TP.HCM');
// mappingType: 'merged'

2. Renamed (Đổi tên)

Phường/xã giữ nguyên ranh giới nhưng đổi tên:

// Phường Ninh Giang → Phường Hòa Thắng
converter.convertAddress('Phường Ninh Giang, Thị xã Ninh Hòa, Khánh Hòa');
// mappingType: 'renamed'

3. Unchanged (Không đổi)

Phường/xã không có thay đổi:

converter.convertAddress('Phường An Lạc, Quận Bình Tân, TP.HCM');
// mappingType: 'unchanged'

📊 Dữ liệu

Thư viện bao gồm:

34 tỉnh/thành phố theo cấu trúc hành chính mới
3,321 phường/xã đã được cập nhật
10,039 mapping records cho việc chuyển đổi

Dữ liệu được cập nhật theo Nghị quyết số 202/2025/QH15 của Quốc hội về việc sắp xếp đơn vị hành chính.

⚠️ Thay đổi quan trọng

Loại bỏ cấp Quận/Huyện

Theo Nghị quyết 202/2025/QH15, cấu trúc hành chính mới không còn cấp quận/huyện:

Trước (3 cấp):

Tỉnh/Thành phố → Quận/Huyện → Phường/Xã

Sau (2 cấp):

Tỉnh/Thành phố → Phường/Xã

Ví dụ chuyển đổi:

Input:

Phường 12, Quận Gò Vấp, Thành phố Hồ Chí Minh

Output:

Phường An Hội Tây, Thành phố Hồ Chí Minh  // Không còn "Quận Gò Vấp"

💻 Ví dụ hoàn chỉnh

import { VietnamAddressConverter } from 'vietnam-address-converter';

async function demo() {
  const converter = new VietnamAddressConverter();
  await converter.initialize();
  
  const testAddresses = [
    'Phường 12, Quận Gò Vấp, TP.HCM',
    'Phường Ninh Giang, Thị xã Ninh Hòa, Khánh Hòa',
    'Xóm Lũng, Xã Văn Luông, Huyện Tân Sơn, Phú Thọ'
  ];
  
  for (const address of testAddresses) {
    const result = converter.convertAddress(address);
    
    if (result.success) {
      console.log(`Input:  ${address}`);
      console.log(`Output: ${result.convertedAddress?.ward}, ${result.convertedAddress?.province}`);
      console.log(`Type:   ${result.mappingInfo?.mappingType}\n`);
    } else {
      console.log(`Error:  ${result.message}\n`);
    }
  }
}

demo();

🛠️ Phát triển

Build từ source

git clone https://github.com/quangtam/vietnam-address-converter
cd vietnam-address-converter
npm install
npm run build

Chạy test

npm test

Ví dụ demo

node examples/demo.ts

🔗 Links & Resources

📋 Documentation

📚 Quick Start Guide - Hướng dẫn nhanh bắt đầu
📖 Full Documentation - Tài liệu đầy đủ
📝 Changelog - Lịch sử thay đổi

🌐 Online Resources

📦 NPM Package - Tải về và cài đặt
💻 GitHub Repository - Source code và issues
🏛️ Nghị quyết 202/2025/QH15 - Văn bản pháp lý gốc

🛠️ Development

🔧 TypeScript Definitions - Type definitions
🧪 Examples - Code examples
🏃‍♂️ Demo Script - Local testing script

🌍 Other Language Implementations

Vietnam Address Converter hiện có sẵn cho nhiều ngôn ngữ lập trình:

🟨 JavaScript/TypeScript: vietnam-address-converter (repo này)
🟦 PHP: vietnam-address-converter-php - Thư viện PHP với API tương tự
🔴 Python: Coming soon...
🟩 Go: Coming soon...

💡 Tất cả implementations đều sử dụng cùng dữ liệu mapping và logic chuyển đổi để đảm bảo tính nhất quán.

🤝 Đóng góp

Chúng tôi hoan nghênh mọi đóng góp! Vui lòng:

Fork dự án
Tạo feature branch (git checkout -b feature/amazing-feature)
Commit thay đổi (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Mở Pull Request

📄 License

MIT License

📞 Liên hệ

Issues: GitHub Issues
Email: [email protected]

🙏 Cảm ơn

Dữ liệu từ thanhtrungit97/dvhcvn
Nghị quyết số 202/2025/QH15 của Quốc hội

Made with ❤️ for Vietnam developers