Vietnamadminunits – Thư viện Python chuyển đổi đơn vị hành chính sau sáp nhập

Link dự án: https://github.com/tranngocminhhieu/vietnamadminunits

Bài toán

Kể từ tháng 7 năm 2025, Khi Việt Nam sáp nhập tỉnh thành (63 tỉnh xuống còn 34 tỉnh). Các ngành nghề kinh doanh online, bao gồm logistic sẽ gặp bài toán chuyển đổi hàng triệu địa chỉ trong hệ thống sang tên mới. Việc này càng khó khăn hơn cho những hệ thống cho phép khách hàng nhập địa chỉ tự do, trong đó có NJV là công ty tôi đang làm. Công ty của tôi sẽ gặp những vấn đề như cùng view báo cáo với đối tác, không so sánh được lợi ích và rủi ro của bảng giá và KPI theo tuyến mới mà đối tác đề nghị.

Nhận thấy những vấn đề sẽ phát sinh trong tương lai, tôi đã chủ động nghiên cứu và phát triển một thư viện (mã nguồn mở) trên Python có tên là vietnamadminunits để xử lý vấn đề này và đóng góp cho cộng đồng.

from vietnamadminunits import convert_address

address = '59 nguyễn sỹ sách , p15, tan binh, hcm' # Old address
admin_unit = convert_address(address)
print(admin_unit)    
Code language: Python (python)
Admin Unit: 59 Nguyễn Sỹ Sách, Phường Tân Sơn, Thành phố Hồ Chí Minh
Attribute       | Value                    
----------------------------------------
province        | Thành phố Hồ Chí Minh    
ward            | Phường Tân Sơn           
street          | 59 Nguyễn Sỹ Sách        
short_province  | Hồ Chí Minh              
short_ward      | Tân Sơn                  
ward_type       | Phường                   
province_code   | 79                       
ward_code       | 27007                    
latitude        | 10.8224                  
longitude       | 106.65 Code language: Shell Session (shell)

Khó khăn và giải pháp

Một phường cũ chia vào hai phường mới

Vấn đề lớn của việc chuyển đổi chính là các phường cũ bị chia thành nhiều phường mới.

Giải pháp:

Bước 1: Thu thập data location (latitude, longitude) và polygon.

  • Đối với 3,321 phường mới thì đã có sẵn location và diện tích km2 (sapnhap.bando.com.vn), có thể suy ra polygon.
  • Đối với 10,040 phường cũ thì thu thập location từ Google Geocoding API.

Bước 2: So sánh location của phường với polygon và location của phường mới.

  • Nếu có duy nhất một phường mới có polygon chứa location của phường cũ → Chọn nó làm phường mới mặc định.
  • Các trường hợp còn lại, chọn phường mới có location gần với location của phường cũ nhất.

Đối với package vietnamadminunits thì đặc biệt hơn một chút. Nếu có địa chỉ chi tiết (số nhà và tên đường) thì sẽ dùng geopy để lấy location online, rồi tiếp tục làm như Bước 2.

Có nhiều cuộc sáp nhập khác từ 2018 đến 2024

Không phải sáp nhập 34 tỉnh thành, mà là sáp nhập trong khi vẫn còn 63 tỉnh thành.

Giải pháp:

  • Tìm kiếm trên Google với từ khóa “{tên tỉnh} sáp nhập {danh sách tên phường cũ}” hoặc “lịch sử hành chính {tên tỉnh}”, dựa vào thông tin trên các trang uy tính để bổ sung danh sách alias keywords.
  • Đối với các phường bị chia thì chọn phường mới có phần chia nhiều người dân nhất.

Một số quận bị chia

Đây là những case bị chia:

  1. Chia thành 2 quận mới, ví dụ: Thành phố Huế (cũ) chia thành Thuận Hóa và Phú Xuân.
  2. Chia vào 2 quận khác, ví dụ: Huyện Lộc Hà thuộc Hà Tĩnh chia xã Hộ Độ cho Thành phố Hà Tĩnh, còn lại chia cho Huyện Thạch Hà.
  3. Cắt vài phường cho quận khác, ví dụ: Huyện Cẩm Xuyên thuộc Hà Tĩnh chia Xã Cẩm Vịnh và Xã Cẩm Bình cho Thành phố Hà Tĩnh.

Giải pháp:

  • Dựa vào phường để chọn quận.
  • Nếu không có phường, chọn quận mặc định. Quận mặc định sẽ là:
    • Quận có nhiều phường nhất.
    • Quận gốc bị cắt.

Triển khai: data/alias_keywords/legacy/divided_district.csv

12 huyện / thị xã / thành phố trùng tên ngắn trong cùng một tỉnh

provincedistrictdistrictShort
Tỉnh Hà TĩnhHuyện Kỳ AnhKỳ Anh (Huyện)
Tỉnh Hà TĩnhThị xã Kỳ AnhKỳ Anh (Thị xã)
Tỉnh Hậu GiangHuyện Long MỹLong Mỹ (Huyện)
Tỉnh Hậu GiangThị xã Long MỹLong Mỹ (Thị xã)
Tỉnh Tiền GiangHuyện Cai LậyCai Lậy (Huyện)
Tỉnh Tiền GiangThị xã Cai LậyCai Lậy (Thị xã)
Tỉnh Trà VinhHuyện Duyên HảiDuyên Hải (Huyện)
Tỉnh Trà VinhThị xã Duyên HảiDuyên Hải (Thị xã)
Tỉnh Đồng ThápHuyện Cao LãnhCao Lãnh (Huyện)
Tỉnh Đồng ThápThành phố Cao LãnhCao Lãnh (Thành phố)
Tỉnh Đồng ThápHuyện Hồng NgựHồng Ngự (Huyện)
Tỉnh Đồng ThápThành phố Hồng NgựHồng Ngự (Thành phố)

Ảnh hưởng đến việc sử dụng tên ngắn làm keyword.

Giải pháp:

  • Thêm từ khóa có kèm type phía sau, và type viết tắt viết trước, ví dụ: kyanhthixa, txkyanh.
  • Ưu tiên Thị xã và Thành phố là mặc định nếu không match type nào. Vì type cao hơn sẽ có diện tích và dân số nhiều hơn.
  • Triển khai dùng phường để chọn quận như Một số quận bị chia.

Chiến lược chuẩn hóa địa chỉ

Sử dụng từ khóa dạng lowcase, tìm từ phải sang trái trên địa chỉ.

import re

# Bước 1: Tạo dict chứa các tỉnh và danh sách từ khóa cho mỗi tỉnh
DICT_PROVINCE = {
    'thanhphohanoi': {
        'provinceKeywords': ['thanhphohanoi', 'hanoi', 'hn'],
        'province': 'Thành phố Hà Nội',
        'provinceShort': 'Hà Nội',
        'provinceLat': 21.0001,
        'provinceLon': 105.698
    },
    'tinhtuyenquang': {
        'provinceKeywords': ['tinhtuyenquang', 'tuyenquang'],
        'province': 'Tỉnh Tuyên Quang',
        'provinceShort': 'Tuyên Quang',
        'provinceLat': 22.4897,
        'provinceLon': 105.099
    }
}

# Bước 2: Xây dựng danh sách từ khóa sắp xếp theo độ dài giảm dần vì regrex sẽ tìm từ trái quá qua phải
province_keywords = sorted(sum([v['provinceKeywords'] for v in DICT_PROVINCE.values()], []), key=len, reverse=True)

# Bước 3: Tạo regex pattern khớp bất kỳ từ khóa
PATTERN_PROVINCE = re.compile('|'.join(province_keywords), flags=re.IGNORECASE)

# Bước 4: Chuẩn hóa địa chỉ trong input (xóa dấu và khoảng cách, chuyển thành lowcase)
address_key = 'hoangkiem,hn'

# Bước 5: Lấy từ khóa tìm được ở cuối địa chỉ
province_keyword = next((m.group() for m in reversed(list(PATTERN_PROVINCE.finditer(address_key)))), None)

# Bước 6: Map trở lại với dict để tìm được quận
province_key = next((k for k, v in DICT_PROVINCE.items() if province_keyword in v['provinceKeywords']), None)

# Output
print(province_key)                              # thanhphohanoi
print(DICT_PROVINCE[province_key]['province'])   # Thành phố Hà Nội
Code language: Python (python)

Kết quả

Đến tháng 9 thì đối tác đã bắt đầu gửi bảng giá và KPI theo đơn vị hành chính mới và thư viện của tôi cũng kịp thời hoàn thiện. Tôi đã có công cụ để chuẩn hóa dữ liệu được dữ liệu và so sánh được lợi ích và rủi ro từ đề nghị của đối tác.

Một số tính năng mà thư viện này làm được:

  • Chuẩn hóa địa chỉ cũ
  • Chuẩn hóa địa chỉ mới
  • Chuyển đổi địa chỉ cũ sang mới
  • Hỗ trợ pandas
Công nghệ sử dụng
Chia sẻ