Đã nửa năm từ sau sự thay đổi lớn về đơn vị hành chính Tháng 7 - 2025, mọi người vẫn còn khó khăn với việc đối chiếu dữ liệu trước và sau sát nhập. Vì vậy mình đã nâng cấp thư viện vietnam-provinces để hỗ trợ việc này.

Từ phiên bản 2026.2.0, bạn đã có thể truy cập dữ liệu phường xã cũ trong module legacy, ví dụ:

>>> from vietnam_provinces import legacy
>>> from rich import print
>>> legacy.Province.from_code(77)
Province(name='Tỉnh Bà Rịa - Vũng Tàu', code=<ProvinceCode.P_77: 77>, division_type=<VietNamDivisionType.TINH: 'tỉnh'>, codename='tinh_ba_ria_vung_tau', phone_code=254)

>>> legacy.District.iter_by_province(77)
<generator object District.iter_by_province.<locals>.<genexpr> at 0x765034d945f0>

>>> print(tuple(legacy.District.iter_by_province(77)))
(
    District(
        name='Thành phố Vũng Tàu',
        code=<DistrictCode.D_747: 747>,
        division_type=<VietNamDivisionType.THANH_PHO: 'thành phố'>,
        codename='thanh_pho_vung_tau',
        province_code=<ProvinceCode.P_77: 77>
    ),
    District(
        name='Thành phố Bà Rịa',
        code=<DistrictCode.D_748: 748>,
        division_type=<VietNamDivisionType.THANH_PHO: 'thành phố'>,
        codename='thanh_pho_ba_ria',
        province_code=<ProvinceCode.P_77: 77>
    ),
    District(
        name='Huyện Châu Đức',
        code=<DistrictCode.D_750: 750>,
        division_type=<VietNamDivisionType.HUYEN: 'huyện'>,
        codename='huyen_chau_duc',
        province_code=<ProvinceCode.P_77: 77>
    ),
    District(
        name='Huyện Xuyên Mộc',
        code=<DistrictCode.D_751: 751>,
        division_type=<VietNamDivisionType.HUYEN: 'huyện'>,
        codename='huyen_xuyen_moc',
        province_code=<ProvinceCode.P_77: 77>
    ),
    District(
        name='Huyện Long Đất',
        code=<DistrictCode.D_753: 753>,
        division_type=<VietNamDivisionType.HUYEN: 'huyện'>,
        codename='huyen_long_dat',
        province_code=<ProvinceCode.P_77: 77>
    ),
    District(
        name='Thị xã Phú Mỹ',
        code=<DistrictCode.D_754: 754>,
        division_type=<VietNamDivisionType.THI_XA: 'thị xã'>,
        codename='thi_xa_phu_my',
        province_code=<ProvinceCode.P_77: 77>
    ),
    District(
        name='Huyện Côn Đảo',
        code=<DistrictCode.D_755: 755>,
        division_type=<VietNamDivisionType.HUYEN: 'huyện'>,
        codename='huyen_con_dao',
        province_code=<ProvinceCode.P_77: 77>
    )
)

Để tra cứu trước và sau sát nhập, có các hàm sau:

• Tìm kiếm các xã hiện nay từ xã cũ, dùng Ward.search_from_legacy(). Ví dụ:

  >>> from vietnam_provinces import Ward
  >>> print(Ward.search_from_legacy('tóc tiên'))
  (
      WardWithLegacy(
          source_code=26731,
          ward=Ward(
              name='Xã Châu Pha',
              code=<WardCode.W_26728: 26728>,
              division_type=<VietNamDivisionType.XA: 'xã'>,
              codename='xa_chau_pha',
              province_code=<ProvinceCode.P_79: 79>
          )
      ),
  )
  

  Kết quả trên có nghĩa là: "Xã Tóc Tiên" cũ có mã 26731, nay đã được nhập vào xã mới là "Xã Châu Pha".

• Xem xã hiện nay được tạo thành từ những xã cũ nào, dùng Ward.get_legacy_sources(). Ví dụ:

  >>> print(Ward.from_code(26728).get_legacy_sources())
  (
      Ward(
          name='Xã Châu Pha',
          code=<WardCode.W_26728: 26728>,
          division_type=<VietNamDivisionType.XA: 'xã'>,
          codename='xa_chau_pha',
          district_code=<DistrictCode.D_754: 754>
      ),
      Ward(
          name='Xã Tóc Tiên',
          code=<WardCode.W_26731: 26731>,
          division_type=<VietNamDivisionType.XA: 'xã'>,
          codename='xa_toc_tien',
          district_code=<DistrictCode.D_754: 754>
      )
  )
  

  Kết quả trên có nghĩa là "Xã Châu Pha" hiện nay (mã 26728) được thành lập từ việc sát nhập "Xã Châu Pha" cũ và "Xã Tóc Tiên".

Có thể đọc thêm tài liệu trên ReadTheDocs để biết thêm các hàm khác.

Một số công ty vận chuyển đã có HTTP API tra cứu tỉnh thành, tại sao nên có thư viện này?

Việc có thư viện dành riêng sẽ tránh được phiền toái khi dùng API bên ngoài: bị ảnh hưởng bởi sự cố mạng, tốn thời gian và băng thông khi tạo API resquest và chờ phản hồi. Ngoài ra việc có thư viện Python sẽ cho phép bạn tự dựng API server riêng, dùng cho nội bộ, phục vụ các ứng dụng khác viết bằng các ngôn ngữ khác.