Package Convert địa chỉ hành chính Việt Nam sau sáp nhập
vietnam-administrative-address – Convert địa chỉ hành chính Việt Nam sau sáp nhập một cách đơn giản
Trong thời gian gần đây, việc thay đổi đơn vị hành chính khiến rất nhiều hệ thống gặp vấn đề với dữ liệu địa chỉ cũ:
- Người dùng nhập địa chỉ theo format cũ trên CCCD
- Dữ liệu DB đang lưu theo quận/huyện cũ
- API cần đồng bộ sang format địa chỉ mới
- Khó normalize địa chỉ để tìm kiếm hoặc mapping
Nếu bạn đang gặp bài toán này, mình đã viết một package npm giúp xử lý việc convert địa chỉ hành chính Việt Nam nhanh hơn:
https://www.npmjs.com/package/vietnam-administrative-address
Package này giải quyết vấn đề gì?
Ví dụ dữ liệu đầu vào:
Tổ 6, Quang Trung, Phủ Lý, Hà Nam
Sau khi parse & convert:
{
"province_name": "Tỉnh Hà Nam",
"district_name": "Thành Phố Phủ Lý",
"ward_name": "Phường Quang Trung"
}
Hoặc convert sang format địa chỉ mới:
Tổ 6, Phường Quang Trung, Hà Nam
Rất phù hợp cho các hệ thống:
- HIS / EMR / bệnh viện
- Kiosk tiếp đón
- eKYC / OCR CCCD
- CRM / ERP
- Logistics
- Đồng bộ dữ liệu hành chính
Tại sao mình viết package này?
Khi làm hệ thống bệnh viện và xử lý OCR CCCD, mình gặp khá nhiều case:
- Địa chỉ trên CCCD là format cũ
- Người dùng nhập thiếu prefix (
P.,Q.,TP.) - Có viết tắt hoặc sai chính tả nhẹ
- Sau sáp nhập cần bỏ cấp quận/huyện
- Cần chuẩn hóa để search chính xác hơn
Trong khi đó chưa có package nào tập trung riêng cho bài toán địa chỉ hành chính Việt Nam theo hướng developer-friendly.
Nên mình build package này với mục tiêu:
- Dễ dùng
- Parse nhanh
- Hỗ trợ dữ liệu địa chỉ Việt Nam
- Tối ưu cho production app
Cài đặt
npm install vietnam-administrative-address
Hoặc:
yarn add vietnam-administrative-address
Focus chính: convertAddressText
Function mình dùng nhiều nhất trong thực tế là:
convertAddressText()
Function này giúp convert địa chỉ cũ sang địa chỉ mới sau sáp nhập hành chính.
Đây là bài toán cực phổ biến khi:
- Dữ liệu DB đang lưu địa chỉ cũ
- OCR CCCD trả về format cũ
- Người dùng nhập địa chỉ theo quận/huyện cũ
- Cần chuẩn hóa địa chỉ trước khi lưu
Cách sử dụng convertAddressText
Ví dụ cơ bản
import { convertAddressText } from "vietnam-administrative-address";
const result = convertAddressText(
"4A Lê Thánh Tông, Phường Cửa Nam, Quận Hoàn Kiếm, Hà Nội"
);
console.log(result);
Kết quả:
4A Lê Thánh Tông, Phường Cửa Nam, Hà Nội
Convert địa chỉ cũ → địa chỉ mới
Input
12 Trần Duy Hưng, Trung Hòa, Cầu Giấy, Hà Nội
Output
12 Trần Duy Hưng, Phường Trung Hòa, Hà Nội
Dữ liệu từ OCR CCCD
Input
Thôn Đông, Xã Hải Bối, Huyện Đông Anh, Hà Nội
Output
Thôn Đông, Xã Hải Bối, Hà Nội
Có thể dùng trực tiếp khi import data
Ví dụ migrate dữ liệu:
import { convertAddressText } from "vietnam-administrative-address";
const addresses = [
"Cửa Nam, Hoàn Kiếm, Hà Nội",
"Quang Trung, Phủ Lý, Hà Nam",
"Dịch Vọng Hậu, Cầu Giấy, Hà Nội"
];
const converted = addresses.map(convertAddressText);
console.log(converted);
Kết quả:
[
"Phường Cửa Nam, Hà Nội",
"Phường Quang Trung, Hà Nam",
"Phường Dịch Vọng Hậu, Hà Nội"
]
Parse địa chỉ chi tiết
Ngoài convert text, package còn hỗ trợ parse địa chỉ thành object.
import { parseAddress } from "vietnam-administrative-address";
const result = parseAddress(
"Tổ 6, Quang Trung, Phủ Lý, Hà Nam"
);
console.log(result);
Kết quả:
{
"province_name": "Tỉnh Hà Nam",
"district_name": "Thành Phố Phủ Lý",
"ward_name": "Phường Quang Trung"
}
Một số điểm mình tập trung tối ưu
1. Hỗ trợ nhiều kiểu input
Package xử lý được:
- Có dấu / không dấu
- Viết tắt
- Thiếu prefix hành chính
- Địa chỉ không đầy đủ
Ví dụ:
Quang Trung, Phu Ly, Ha Nam
vẫn parse được.
2. Tối ưu cho developer
API đơn giản:
convertAddressText(text)
parseAddress(text)
Không cần setup phức tạp.
Github & package
- 📦 NPM Package: https://www.npmjs.com/package/vietnam-administrative-address
- 💻 Github Repository: https://github.com/hoatepdev/vietnam_administrative_address
Dữ liệu được xây dựng và cập nhật từ: https://github.com/vietmap-company/vietnam_administrative_address
Cảm ơn vietmap
Kết
Bài toán địa chỉ hành chính ở Việt Nam khá “đặc sản”, đặc biệt sau các đợt thay đổi đơn vị hành chính gần đây.
Hy vọng package này giúp anh em tiết kiệm thời gian hơn khi xử lý dữ liệu địa chỉ trong production.
Nếu thấy hữu ích nhớ ⭐ repo giúp mình nhé.
Happy codingggggggg
All rights reserved
