| Name | vietnam-provinces JSON |
| Version |
2025.8.1
JSON |
| download |
| home_page | None |
| Summary | Library to provide list of Vietnam administrative divisions (tỉnh thành, quận huyện, phường xã). |
| upload_time | 2025-08-09 11:59:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4.0,>=3.10 |
| license | None |
| keywords |
vietnam
administrative
division
locality
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
================
VietnamProvinces
================
|image love| |image pypi| |common changelog|
[`Tiếng Việt <vietnamese_>`_]
Library to provide list of Vietnam administrative divisions (tỉnh thành, phường xã, after the rearrangement in July 2025) with the name and code as defined by `Draft of new administrative units <draft_new_units_>`_ (Tổng cục Thống kê).
Example:
.. code-block:: json
{
"name": "Tuyên Quang",
"code": 8,
"codename": "tuyen_quang",
"division_type": "tỉnh",
"phone_code": 207,
"wards": [
{
"name": "Xã Thượng Lâm",
"code": 2269,
"codename": "xa_thuong_lam",
"division_type": "xã",
"short_codename": "thuong_lam"
},
{
"name": "Xã Lâm Bình",
"code": 2266,
"codename": "xa_lam_binh",
"division_type": "xã",
"short_codename": "lam_binh"
},
]
}
This library provides data in these forms:
1. JSON
This 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.
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:
.. code-block:: python
import orjson
import rapidjson
from vietnam_provinces import NESTED_DIVISIONS_JSON_PATH
# With rapidjson
with NESTED_DIVISIONS_JSON_PATH.open() as f:
rapidjson.load(f)
# With orjson
orjson.loads(NESTED_DIVISIONS_JSON_PATH.read_bytes())
2. Python data type
This data is useful for some applications which need to access the data more often.
There are two kinds of objects, first is the object presenting a single province or ward, second is province code or ward code in form of `enum`, which you can import in Python code:
.. code-block:: python
>>> from vietnam_provinces import ProvinceCode, Province, WardCode, Ward
>>> Province.from_code(ProvinceCode.P_15)
Province(name='Lào Cai', code=<ProvinceCode.P_15: 15>, division_type=<VietNamDivisionType.TINH: 'tỉnh'>, codename='lao_cai', phone_code=214)
>>> Ward.from_code(23425)
Ward(name='Xã Tu Mơ Rông', code=<WardCode.W_23425: 23425>, division_type=<VietNamDivisionType.XA: 'xã'>, codename='xa_tu_mo_rong', province_code=<ProvinceCode.P_51: 51>)
To know if the data is up-to-date, check the ``__data_version__`` attribute of the module:
.. code-block:: python
>>> import vietnam_provinces
>>> vietnam_provinces.__data_version__
'2025-08-02'
Install
-------
.. code-block:: sh
python -m pip install vietnam-provinces
# or
uv add vietnam-provinces
This library is compatible with Python 3.10+.
Development
-----------
In 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 data
~~~~~~~~~~~
In 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 when `GSOVN <gso_vn_>`_ replaces 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 it *Xa_2025-01-04.csv*.
- Run this tool to compute data to JSON format:
.. code-block:: sh
python3 -m dev -w dev/seed-data/2025-07/Cap-xa.csv -p dev/seed-data/2025-07/Cap-tinh.csv -f nested-json
You can run
.. code-block:: sh
python3 -m dev --help
to 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 code
~~~~~~~~~~~~~~~~~~~~
.. code-block:: sh
python3 -m dev -w dev/seed-data/2025-07/Cap-xa.csv -p dev/seed-data/2025-07/Cap-tinh.csv -f python
Data source
~~~~~~~~~~~
- Name and code of provinces, and wards: `General Statistics Office of Viet Nam <gso_vn_>`_.
- Phone area code: `Thái Bình province's department of Information and Communication <tb_ic_>`_.
Credit
------
Given to you by `Nguyễn Hồng Quân <quan_>`_, after nights and weekends.
.. |image love| image:: https://madewithlove.now.sh/vn?heart=true&colorA=%23ffcd00&colorB=%23da251d
.. |image pypi| image:: https://badgen.net/pypi/v/vietnam-provinces
:target: https://pypi.org/project/vietnam-provinces/
.. |common changelog| image:: https://common-changelog.org/badge.svg
:target: https://common-changelog.org
.. _vietnamese: README.vi_VN.rst
.. _gso_vn: https://danhmuchanhchinh.gso.gov.vn/
.. _draft_new_units: https://chinhphu.vn/du-thao-vbqppl/du-thao-quyet-dinh-cua-thu-tuong-chinh-phu-ban-hanh-bang-danh-muc-va-ma-so-cac-don-vi-hanh-chinh-7546
.. _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
.. _dataclass: https://docs.python.org/3/library/dataclasses.html
.. _pydantic: https://pypi.org/project/pydantic/
.. _quan: https://quan.hoabinh.vn
Raw data
{
"_id": null,
"home_page": null,
"name": "vietnam-provinces",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "Vietnam, administrative, division, locality",
"author": null,
"author_email": "Nguy\u1ec5n H\u1ed3ng Qu\u00e2n <ng.hong.quan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/59/6e/969ed9123cf07851a562e159e1a23590130facd5fd90e499902d15b35f80/vietnam_provinces-2025.8.1.tar.gz",
"platform": null,
"description": "================\nVietnamProvinces\n================\n\n|image love| |image pypi| |common changelog|\n\n[`Ti\u1ebfng Vi\u1ec7t <vietnamese_>`_]\n\nLibrary to provide list of Vietnam administrative divisions (t\u1ec9nh th\u00e0nh, ph\u01b0\u1eddng x\u00e3, after the rearrangement in July 2025) with the name and code as defined by `Draft of new administrative units <draft_new_units_>`_ (T\u1ed5ng c\u1ee5c Th\u1ed1ng k\u00ea).\n\nExample:\n\n.. code-block:: json\n\n {\n \"name\": \"Tuy\u00ean Quang\",\n \"code\": 8,\n \"codename\": \"tuyen_quang\",\n \"division_type\": \"t\u1ec9nh\",\n \"phone_code\": 207,\n \"wards\": [\n {\n \"name\": \"X\u00e3 Th\u01b0\u1ee3ng L\u00e2m\",\n \"code\": 2269,\n \"codename\": \"xa_thuong_lam\",\n \"division_type\": \"x\u00e3\",\n \"short_codename\": \"thuong_lam\"\n },\n {\n \"name\": \"X\u00e3 L\u00e2m B\u00ecnh\",\n \"code\": 2266,\n \"codename\": \"xa_lam_binh\",\n \"division_type\": \"x\u00e3\",\n \"short_codename\": \"lam_binh\"\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\n\n2. Python data type\n\nThis data is useful for some applications which need to access the data more often.\nThere are two kinds of objects, first is the object presenting a single province or ward, second is province code or ward code in form of `enum`, which you can import in Python code:\n\n.. code-block:: python\n\n >>> from vietnam_provinces import ProvinceCode, Province, WardCode, Ward\n\n >>> Province.from_code(ProvinceCode.P_15)\n Province(name='L\u00e0o Cai', code=<ProvinceCode.P_15: 15>, division_type=<VietNamDivisionType.TINH: 't\u1ec9nh'>, codename='lao_cai', phone_code=214)\n\n >>> Ward.from_code(23425)\n Ward(name='X\u00e3 Tu M\u01a1 R\u00f4ng', code=<WardCode.W_23425: 23425>, division_type=<VietNamDivisionType.XA: 'x\u00e3'>, codename='xa_tu_mo_rong', province_code=<ProvinceCode.P_51: 51>)\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 >>> import vietnam_provinces\n >>> vietnam_provinces.__data_version__\n '2025-08-02'\n\n\nInstall\n-------\n\n.. code-block:: sh\n\n python -m pip install vietnam-provinces\n # or\n uv add 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 <gso_vn_>`_ replaces their software).\n- Find the button \"Xu\u1ea5t Excel\".\n- Tick the \"Qu\u1eadn Huy\u1ec7n Ph\u01b0\u1eddng X\u00e3\" 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 -w dev/seed-data/2025-07/Cap-xa.csv -p dev/seed-data/2025-07/Cap-tinh.csv -f nested-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 -w dev/seed-data/2025-07/Cap-xa.csv -p dev/seed-data/2025-07/Cap-tinh.csv -f python\n\n\nData source\n~~~~~~~~~~~\n\n- Name and code of provinces, and wards: `General Statistics Office of Viet Nam <gso_vn_>`_.\n- Phone area code: `Th\u00e1i B\u00ecnh province's department of Information and Communication <tb_ic_>`_.\n\n\nCredit\n------\n\nGiven to you by `Nguy\u1ec5n H\u1ed3ng Qu\u00e2n <quan_>`_, after nights and weekends.\n\n\n.. |image love| image:: https://madewithlove.now.sh/vn?heart=true&colorA=%23ffcd00&colorB=%23da251d\n.. |image pypi| image:: https://badgen.net/pypi/v/vietnam-provinces\n :target: https://pypi.org/project/vietnam-provinces/\n.. |common changelog| image:: https://common-changelog.org/badge.svg\n :target: https://common-changelog.org\n.. _vietnamese: README.vi_VN.rst\n.. _gso_vn: https://danhmuchanhchinh.gso.gov.vn/\n.. _draft_new_units: https://chinhphu.vn/du-thao-vbqppl/du-thao-quyet-dinh-cua-thu-tuong-chinh-phu-ban-hanh-bang-danh-muc-va-ma-so-cac-don-vi-hanh-chinh-7546\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.. _pydantic: https://pypi.org/project/pydantic/\n.. _quan: https://quan.hoabinh.vn\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Library to provide list of Vietnam administrative divisions (t\u1ec9nh th\u00e0nh, qu\u1eadn huy\u1ec7n, ph\u01b0\u1eddng x\u00e3).",
"version": "2025.8.1",
"project_urls": {
"Changelog": "https://github.com/sunshine-tech/VietnamProvinces/blob/main/CHANGELOG.md",
"Documentation": "https://vietnamprovinces.readthedocs.io",
"Homepage": "https://github.com/sunshine-tech/VietnamProvinces",
"Repository": "https://github.com/sunshine-tech/VietnamProvinces.git"
},
"split_keywords": [
"vietnam",
" administrative",
" division",
" locality"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b996676145efa438291c7b0b089ca038a21e7b0a2d77246b804cfd4844ba3c66",
"md5": "98330c944c36d71697477baf10fc5cd5",
"sha256": "05e2bc43a57a0e881c439d7c210f0e8036c5e5c2305ae9010ca896f75eaf44d1"
},
"downloads": -1,
"filename": "vietnam_provinces-2025.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "98330c944c36d71697477baf10fc5cd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 227820,
"upload_time": "2025-08-09T11:59:44",
"upload_time_iso_8601": "2025-08-09T11:59:44.000204Z",
"url": "https://files.pythonhosted.org/packages/b9/96/676145efa438291c7b0b089ca038a21e7b0a2d77246b804cfd4844ba3c66/vietnam_provinces-2025.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "596e969ed9123cf07851a562e159e1a23590130facd5fd90e499902d15b35f80",
"md5": "54a55d59f2f520fbb916a95aa3e1613b",
"sha256": "8402b9fd2f50c2ac755b57505a85b5bca54e4fa3df2ae78b4e2b6b77c754e9af"
},
"downloads": -1,
"filename": "vietnam_provinces-2025.8.1.tar.gz",
"has_sig": false,
"md5_digest": "54a55d59f2f520fbb916a95aa3e1613b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 221713,
"upload_time": "2025-08-09T11:59:46",
"upload_time_iso_8601": "2025-08-09T11:59:46.543219Z",
"url": "https://files.pythonhosted.org/packages/59/6e/969ed9123cf07851a562e159e1a23590130facd5fd90e499902d15b35f80/vietnam_provinces-2025.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 11:59:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sunshine-tech",
"github_project": "VietnamProvinces",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "vietnam-provinces"
}
