{"id":13616621,"url":"https://github.com/sunshine-tech/VietnamProvinces","last_synced_at":"2025-04-14T03:31:14.133Z","repository":{"id":57477461,"uuid":"244206371","full_name":"sunshine-tech/VietnamProvinces","owner":"sunshine-tech","description":"Library to provide list of Vietnam administrative divisions (tỉnh thành, quận huyện, phường xã)","archived":false,"fork":false,"pushed_at":"2025-01-04T16:47:58.000Z","size":2592,"stargazers_count":48,"open_issues_count":4,"forks_count":15,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-08T14:47:35.991Z","etag":null,"topics":["administrative","locality","made-in-vietnam","vietnam"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sunshine-tech.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-01T19:00:02.000Z","updated_at":"2025-03-28T01:59:07.000Z","dependencies_parsed_at":"2024-06-21T14:19:16.923Z","dependency_job_id":"5835931d-45f9-471b-90b2-71fcb3dd9d6b","html_url":"https://github.com/sunshine-tech/VietnamProvinces","commit_stats":{"total_commits":43,"total_committers":1,"mean_commits":43.0,"dds":0.0,"last_synced_commit":"5c5d57936f4203997e574380b75b24b98ffaa1db"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunshine-tech%2FVietnamProvinces","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunshine-tech%2FVietnamProvinces/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunshine-tech%2FVietnamProvinces/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunshine-tech%2FVietnamProvinces/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sunshine-tech","download_url":"https://codeload.github.com/sunshine-tech/VietnamProvinces/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248815514,"owners_count":21165938,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["administrative","locality","made-in-vietnam","vietnam"],"created_at":"2024-08-01T20:01:31.031Z","updated_at":"2025-04-14T03:31:14.127Z","avatar_url":"https://github.com/sunshine-tech.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"================\nVietnamProvinces\n================\n\n|image love| |image pypi|\n\n[`Tiếng Việt \u003cvietnamese_\u003e`_]\n\nLibrary 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 by `General Statistics Office of Viet Nam \u003cgso_vn_\u003e`_ (Tổng cục Thống kê).\n\nExample:\n\n.. code-block:: json\n\n    {\n        \"name\": \"Tỉnh Cà Mau\",\n        \"code\": 96,\n        \"codename\": \"tinh_ca_mau\",\n        \"division_type\": \"tỉnh\",\n        \"phone_code\": 290,\n        \"districts\": [\n            {\n                \"name\": \"Huyện Đầm Dơi\",\n                \"code\": 970,\n                \"codename\": \"huyen_dam_doi\",\n                \"division_type\": \"huyện\",\n                \"wards\": [\n                    {\n                        \"name\": \"Thị trấn Đầm Dơi\",\n                        \"code\": 32152,\n                        \"codename\": \"thi_tran_dam_doi\",\n                        \"division_type\": \"thị trấn\"\n                    },\n                    {\n                        \"name\": \"Xã Tạ An Khương\",\n                        \"code\": 32155,\n                        \"codename\": \"xa_ta_an_khuong\",\n                        \"division_type\": \"xã\"\n                    },\n                ]\n            }\n        ]\n    }\n\nThis library provides data in these forms:\n\n1. JSON\n\nThis 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 in *data* folder. You can get the file path via ``vietnam_provinces.NESTED_DIVISIONS_JSON_PATH`` variable.\n\nNote 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:\n\n.. code-block:: python\n\n    import orjson\n    import rapidjson\n    from vietnam_provinces import NESTED_DIVISIONS_JSON_PATH\n\n    # With rapidjson\n    with NESTED_DIVISIONS_JSON_PATH.open() as f:\n        rapidjson.load(f)\n\n    # With orjson\n    orjson.loads(NESTED_DIVISIONS_JSON_PATH.read_bytes())\n\nDue to the big amount of data (10609 wards all over Viet Nam), this loading will be slow.\n\n\n2. Python data type\n\nThis data is useful for some applications which need to access the data more often. They are built as ``Enum``, where you can import in Python code:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from vietnam_provinces.enums import ProvinceEnum, ProvinceDEnum, DistrictEnum, DistrictDEnum\n\n    \u003e\u003e\u003e ProvinceEnum.P_77\n    \u003cProvinceEnum.P_77: Province(name='Tỉnh Bà Rịa - Vũng Tàu', code=77, division_type=\u003cVietNamDivisionType.TINH: 'tỉnh'\u003e, codename='tinh_ba_ria_vung_tau', phone_code=254)\u003e\n\n    \u003e\u003e\u003e ProvinceDEnum.BA_RIA_VUNG_TAU\n    \u003cProvinceDEnum.BA_RIA_VUNG_TAU: Province(name='Tỉnh Bà Rịa - Vũng Tàu', code=77, division_type=\u003cVietNamDivisionType.TINH: 'tỉnh'\u003e, codename='tinh_ba_ria_vung_tau', phone_code=254)\u003e\n\n    \u003e\u003e\u003e DistrictEnum.D_624\n    \u003e\u003e\u003e \u003cDistrictEnum.D_624: District(name='Thị xã Ayun Pa', code=624, division_type=\u003cVietNamDivisionType.THI_XA: 'thị xã'\u003e, codename='thi_xa_ayun_pa', province_code=64)\u003e\n\n    \u003e\u003e\u003e DistrictDEnum.AYUN_PA_GL\n    \u003cDistrictDEnum.AYUN_PA_GL: District(name='Thị xã Ayun Pa', code=624, division_type=\u003cVietNamDivisionType.THI_XA: 'thị xã'\u003e, codename='thi_xa_ayun_pa', province_code=64)\u003e\n\n    \u003e\u003e\u003e from vietnam_provinces.enums.wards import WardEnum, WardDEnum\n\n    \u003e\u003e\u003e WardEnum.W_7450\n    \u003cWardEnum.W_7450: Ward(name='Xã Đông Hưng', code=7450, division_type=\u003cVietNamDivisionType.XA: 'xã'\u003e, codename='xa_dong_hung', district_code=218)\u003e\n\n    \u003e\u003e\u003e WardDEnum.BG_DONG_HUNG_7450\n    \u003cWardDEnum.BG_DONG_HUNG_7450: Ward(name='Xã Đông Hưng', code=7450, division_type=\u003cVietNamDivisionType.XA: 'xã'\u003e, codename='xa_dong_hung', district_code=218)\u003e\n\n\nLoading wards this way is far more faster than the JSON option.\n\nThey are made as ``Enum``, so that library user can take advantage of auto-complete feature of IDE/code editors in development. It prevents typo mistake.\n\nThe Ward Enum has two variants:\n\n- ``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).\n\n- ``WardDEnum``: Has more readable member name (``D`` means \"descriptive\"), to help the application code easier to reason about. For example, looking at ``WardDEnum.BT_PHAN_RI_CUA_22972``, the programmer can guess that this ward is \"Phan Rí Cửa\", of \"Bình Thuận\" province.\n\nSimilarly, other levels (District, Province) also have two variants of Enum.\n\nExample of looking up ``Ward``, ``District``, ``Province`` with theirs numeric code:\n\n.. code-block:: python\n\n    # Assume that you are loading user info from your database\n    user_info = load_user_info()\n\n    province_code = user_info['province_code']\n    province = ProvinceEnum[f'P_{province_code}'].value\n\nUnlike ``ProvinceDEnum``, ``DistrictDEnum``, the ``WardDEnum`` has 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.\n\nBecause the ``WardEnum`` has 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.\n\n\nMember of these enums, the ``Province``, ``District`` and ``Ward`` data types, can be imported from top-level of ``vietnam_provinces``.\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from vietnam_provinces import Province, District, Ward\n\n\nTo know if the data is up-to-date, check the `__data_version__` attribute of the module:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import vietnam_provinces\n    \u003e\u003e\u003e vietnam_provinces.__data_version__\n    '2025-01-04'\n\n\nInstall\n-------\n\n.. code-block:: sh\n\n    pip3 install vietnam-provinces\n\n\nThis library is compatible with Python 3.10+.\n\n\nDevelopment\n-----------\n\nIn development, this project has a tool to convert data from government sources.\n\nThe 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.\n\nThe tool is tested on Linux only (may not run on Windows).\n\nUpdate data\n~~~~~~~~~~~\n\nIn the future, when the authority reorganize administrative divisions, we need to collect this data again from GSOVN website. Do:\n\n- Go to: https://danhmuchanhchinh.gso.gov.vn/ (this URL may change when `GSOVN \u003cgso_vn_\u003e`_ replaces their software).\n- Find the button \"Xuất Excel\".\n- Tick the \"Quận Huyện Phường Xã\" checkbox.\n- Click the button to export and download list of units in Excel (XLS) file.\n- Use LibreOffice to convert Excel file to CSV file. For example, we name it *Xa_2025-01-04.csv*.\n- Run this tool to compute data to JSON format:\n\n.. code-block:: sh\n\n    python3 -m dev -i dev/seed-data/Xa_2025-01-04.csv -o vietnam_provinces/data/nested-divisions.json\n\nYou can run\n\n.. code-block:: sh\n\n    python3 -m dev --help\n\nto see more options of that tool.\n\nNote that this tool is only available in the source folder (cloned from Git). It is not included in the distributable Python package.\n\n\nGenerate Python code\n~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: sh\n\n    python3 -m dev -i dev/seed-data/Xa_2025-01-04.csv -f python\n\n\nData source\n~~~~~~~~~~~\n\n- Name and code of provinces, districts and wards:  `General Statistics Office of Viet Nam \u003cgso_vn_\u003e`_.\n- Phone area code: `Thái Bình province's department of Information and Communication \u003ctb_ic_\u003e`_.\n\n\nCredit\n------\n\nGiven to you by `Nguyễn Hồng Quân \u003cquan_\u003e`_, after nights and weekends.\n\n\n.. |image love| image:: https://madewithlove.now.sh/vn?heart=true\u0026colorA=%23ffcd00\u0026colorB=%23da251d\n.. |image pypi| image:: https://badgen.net/pypi/v/vietnam-provinces\n   :target: https://pypi.org/project/vietnam-provinces/\n.. _vietnamese: README.vi_VN.rst\n.. _gso_vn: https://www.gso.gov.vn/\n.. _tb_ic: https://sotttt.thaibinh.gov.vn/tin-tuc/buu-chinh-vien-thong/tra-cuu-ma-vung-dien-thoai-co-dinh-mat-dat-ma-mang-dien-thoa2.html\n.. _dataclass: https://docs.python.org/3/library/dataclasses.html\n.. _fast-enum: https://pypi.org/project/fastenumplus/\n.. _pydantic: https://pypi.org/project/pydantic/\n.. _Black: https://github.com/psf/black\n.. _quan: https://quan.hoabinh.vn\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunshine-tech%2FVietnamProvinces","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsunshine-tech%2FVietnamProvinces","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunshine-tech%2FVietnamProvinces/lists"}