Package: vietnam-provinces
[Tiếng Việt]Library to provide list of Vietnam administrative divisions (tỉnh thành, quận huyện, phường xã) with the name and code as defined byGeneral Statistics Office of Viet Nam(Tổng cục Thống kê).Example:{"name":"Tỉnh Cà Mau","code":96,"codename":"tinh_ca_mau","division_type":"tỉnh","phone_code":290,"districts":[{"name":"Huyện Đầm Dơi","code":970,"codename":"huyen_dam_doi","division_type":"huyện","wards":[{"name":"Thị trấn Đầm Dơi","code":32152,"codename":"thi_tran_dam_doi","division_type":"thị trấn"},{"name":"Xã Tạ An Khương","code":32155,"codename":"xa_ta_an_khuong","division_type":"xã"},]}]}This library provides data in these forms:JSONThis data is suitable for applications which don’t need to access the data often. They are fine with loading JSON and extract information from it. The JSON files are saved indatafolder. You can get the file path viavietnam_provinces.NESTED_DIVISIONS_JSON_PATHvariable.Note that this variable only returns the path of the file, not the content. It is up to application developer to use any method to parse the JSON. For example:importorjsonimportrapidjsonfromvietnam_provincesimportNESTED_DIVISIONS_JSON_PATH# With rapidjsonwithNESTED_DIVISIONS_JSON_PATH.open()asf:rapidjson.load(f)# With orjsonorjson.loads(NESTED_DIVISIONS_JSON_PATH.read_bytes())Due to the big amount of data (10609 wards all over Viet Nam), this loading will be slow.Python data typeThis data is useful for some applications which need to access the data more often. They are built asEnum, where you can import in Python code:>>>fromvietnam_provinces.enumsimportProvinceEnum,ProvinceDEnum,DistrictEnum,DistrictDEnum>>>ProvinceEnum.P_77<ProvinceEnum.P_77:Province(name='Tỉnh Bà Rịa - Vũng Tàu',code=77,division_type=<VietNamDivisionType.TINH:'tỉnh'>,codename='tinh_ba_ria_vung_tau',phone_code=254)>>>>ProvinceDEnum.BA_RIA_VUNG_TAU<ProvinceDEnum.BA_RIA_VUNG_TAU:Province(name='Tỉnh Bà Rịa - Vũng Tàu',code=77,division_type=<VietNamDivisionType.TINH:'tỉnh'>,codename='tinh_ba_ria_vung_tau',phone_code=254)>>>>DistrictEnum.D_624>>><DistrictEnum.D_624:District(name='Thị xã Ayun Pa',code=624,division_type=<VietNamDivisionType.THI_XA:'thị xã'>,codename='thi_xa_ayun_pa',province_code=64)>>>>DistrictDEnum.AYUN_PA_GL<DistrictDEnum.AYUN_PA_GL:District(name='Thị xã Ayun Pa',code=624,division_type=<VietNamDivisionType.THI_XA:'thị xã'>,codename='thi_xa_ayun_pa',province_code=64)>>>>fromvietnam_provinces.enums.wardsimportWardEnum,WardDEnum>>>WardEnum.W_7450<WardEnum.W_7450:Ward(name='Xã Đông Hưng',code=7450,division_type=<VietNamDivisionType.XA:'xã'>,codename='xa_dong_hung',district_code=218)>>>>WardDEnum.BG_DONG_HUNG_7450<WardDEnum.BG_DONG_HUNG_7450:Ward(name='Xã Đông Hưng',code=7450,division_type=<VietNamDivisionType.XA:'xã'>,codename='xa_dong_hung',district_code=218)>Loading wards this way is far more faster than the JSON option.They are made asEnum, so that library user can take advantage of auto-complete feature of IDE/code editors in development. It prevents typo mistake.The Ward Enum has two variants:WardEnum: Has member name in form of numeric ward code (W_28912). It helps look up a ward by its code (which is a most-seen use case).WardDEnum: Has more readable member name (Dmeans “descriptive”), to help the application code easier to reason about. For example, looking atWardDEnum.BT_PHAN_RI_CUA_22972, the programmer can guess that this ward is “Phan Rí Cửa”, of “Bình Thuận” province.Similarly, other levels (District, Province) also have two variants of Enum.Example of looking upWard,District,Provincewith theirs numeric code:# Assume that you are loading user info from your databaseuser_info=load_user_info()province_code=user_info['province_code']province=ProvinceEnum[f'P_{province_code}'].valueUnlikeProvinceDEnum,DistrictDEnum, theWardDEnumhas ward code in member name. It is because there are too many Vietnamese wards with the same name. There is no way to build unique ID for wards, with pure Latin letters (Vietnamese punctuations stripped), even if we add district and province info to the ID. Let’s take “Xã Đông Thành” and “Xã Đông Thạnh” as example. Both belong to “Huyện Bình Minh” of “Vĩnh Long”, both produces ID name “DONG_THANH”. Although Python allows Unicode as ID name, like “ĐÔNG_THẠNH”, but it is not practical yet because the code formatter tool (Black) will still normalizes it to Latin form.Because theWardEnumhas many records (10609 in February 2021) and may not be needed in some applications, I move it to separate module, to avoid loading automatically to application.Member of these enums, theProvince,DistrictandWarddata types, can be imported from top-level ofvietnam_provinces.>>>fromvietnam_provincesimportProvince,District,WardInstallpip3installvietnam-provincesThis library is compatible with Python 3.7+.DevelopmentIn development, this project has a tool to convert data from government sources.The tool doesn’t directly crawl data from government websites because the data rarely change (it doesn’t worth developing the feature which you only need to use each ten years), and because those websites provide data in unfriendly Microsoft Office formats.The tool is tested on Linux only (may not run on Windows).Update dataIn the future, when the authority reorganize administrative divisions, we need to collect this data again from GSOVN website. Do:Go to:https://danhmuchanhchinh.gso.gov.vn/(this URL may change whenGSOVNreplaces their software).Find the button “Xuất Excel”.Tick the “Quận Huyện Phường Xã” checkbox.Click the button to export and download list of units in Excel (XLS) file.Use LibreOffice to convert Excel file to CSV file. For example, we name itXa_2023-05-07.csv.Run this tool to compute data to JSON format:python3-mdev-idev/seed-data/Xa_2023-05-07.csv-ovietnam_provinces/data/nested-divisions.jsonYou can runpython3-mdev--helpto see more options of that tool.Note that this tool is only available in the source folder (cloned from Git). It is not included in the distributable Python package.Generate Python codepython3-mdev-idev/seed-data/Xa_2023-05-07.csv-fpythonData sourceName and code of provinces, districts and wards:General Statistics Office of Viet Nam.Phone area code:Thái Bình province’s department of Information and Communication.CreditGiven to you byNguyễn Hồng Quân, after nights and weekends.