| Name | barangay JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | Philippines Standard Geographic Code (PSGC) 2025 Python package, JSON, and YAML. |
| upload_time | 2025-08-13 16:28:31 |
| maintainer | None |
| docs_url | None |
| author | bendlikeabamboo |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
philippines
geography
barangay
region
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# barangay
[<p style="text-align:center;">](https://pypi.org/project/barangay/) [](https://opensource.org/licenses/MIT) [](https://pepy.tech/projects/barangay) [](https://github.com/bendlikeabamboo/barangay/actions/workflows/publish.yaml)<p>
<p>
Philippines Standard Geographic Code (PSGC) 2025 Python package for Philippine regions,
provinces, cities, municipalities, and barangay. Available in JSON, YAML, and Python
dictionary formats. Latest and updated as of July 2025.
__SOURCE FILE__: [2025-07-08 PSGC Release](https://psa.gov.ph/classification/psgc/node/1684077694) <br>
__PyPI__: https://pypi.org/project/barangay/ <br>
__Installation__: `pip install barangay`
## Features
- Comprehensive, up-to-date list of Philippine barangays and their administrative
hierarchy based on Philippine Standard Geographic Code ([PSGC](https://psa.gov.ph/classification/psgc))
- Data also available in both JSON and YAML formats under `barangay/`
- Available in different data models
- Direct Nested Hierarchical Model
- Metadata-rich Recursive Hierarchical Model
- Metadata-rich Flat Model
- Easy integration with Python projects.
## Installation
```bash
pip install barangay
```
## Usage
Sample usage in `notebooks/sample_usage.ipynb`
### barangay.BARANGAY: Direct Nested Hierarchical Model
Traversing `barangay.BARANGAY` is straightforward since it’s a purely nested dictionary
composed of names, with no additional metadata.
```python
from barangay import BARANGAY
# Example lookup process and dictionary traversal
all_regions = BARANGAY.keys()
# Looking for NCR Cities & Municipalities
ncr_cities_and_municipalities = list(BARANGAY["National Capital Region (NCR)"].keys())
print(f"NCR Cities & Municipalities: {ncr_cities_and_municipalities}")
# Looking for Municipalities of Cities of Manila
municipalities_of_manila = list(BARANGAY["National Capital Region (NCR)"][
"City of Manila"
].keys())
print(f"Municipalities of Manila: {municipalities_of_manila}")
# Looking for Barangays in Binondo
brgy_of_binondo = BARANGAY["National Capital Region (NCR)"]["City of Manila"][
"Binondo"
]
print(f"Brgys of Binondo: {brgy_of_binondo}")
```
The provided code demonstrates a simple traversal of the `BARANGAY` nested dictionary.
This dictionary, however, has only simple parent-child structure that doesn't fully
represent the complex geographical hierarchy of the Philippines. For example, some
municipalities like __Pateros__ are directly under a region, and certain highly
urbanized cities (__HUCs__) such as __Tacloban City__ and __Davao City__ are not part of
a province.
This simplified structure can make it challenging to implement accurate address
selectors with labeled forms where distinctions between municipalities and cities and
provinces are important. To address this, I developed `barangay.BARANGAY_EXTENDED`, a
more complex fractal dictionary that accurately mirrors the intricate geographical
divisions of the Philippines.
### barangay.BARANGAY_EXTENDED: Metadata-rich Recursive Hierarchical Model
Traversing `barangay.BARANGAY_EXTENDED` is slightly more involved, as each location
includes rich metadata stored in dictionary fields. Instead of simple key-value pairs,
traversal involves navigating lists of dictionaries—adding a bit of complexity, but also
unlocking far greater flexibility and precision. This structure enables more accurate
modeling of the Philippines' administrative divisions, making it ideal for applications
that require detailed address handling or contextual geographic data.
```python
from barangay import BARANGAY_EXTENDED
from pprint import pprint
# Listing all component locations under Philippines
philippine_components = [item["name"] for item in BARANGAY_EXTENDED["components"]]
print("philippine_components: ")
pprint(philippine_components)
print("\n\n")
# retrieving National Capital Region (NCR) location data
ncr = [
item
for item in BARANGAY_EXTENDED["components"]
if item["name"] == "National Capital Region (NCR)"
][0]
# Listing all component locations under NCR. In the output, notice tha Pateros is a
# municipality directly under a region, which is unusual but possible, nonetheless.
ncr_components = [(item["name"], item["type"]) for item in ncr["components"]]
print("ncr_components")
pprint(ncr_components)
print("\n\n")
# Retrieving City of Manila location data
city_of_manila = [
item for item in ncr["components"] if item["name"] == "City of Manila"
][0]
# Listing all component locations under City of Manila
city_of_manila_components = [
(item["name"], item["type"]) for item in city_of_manila["components"]
]
print("city_of_manila_components")
pprint(city_of_manila_components)
print("\n\n")
# Retrieving Sta Ana location data
sta_ana = [
item for item in city_of_manila["components"] if item["name"] == "Santa Ana"
][0]
# Listing all component locations under Santa Ana (which are now the Barangay)
santa_ana_components = [
(item["name"], item["type"]) for item in sta_ana["components"]
]
print("santa_ana_components")
pprint(santa_ana_components)
print("\n\n")
```
### barangay.BARANGAY_FLAT: Metadata-rich Flat Model
The barangay.BARANGAY_FLAT structure offers a fully flattened list of all Philippine
administrative units—regions, provinces, cities, municipalities, and barangays—with rich
metadata for each entry. This format is ideal for search, filtering, and integration
with tabular data workflows such as pandas DataFrames or database imports.
```python
from barangay import BARANGAY_FLAT
# Looking for Brgy. Marayos in Mindoro
brgy_marayos = [loc for loc in BARANGAY_FLAT if loc["name"]=="Marayos"]
print(brgy_marayos)
# From here we can now trace its hierarchy by following parent_psgc_id
brgy_marayos_parent = [loc for loc in BARANGAY_FLAT if loc["psgc_id"]=="1705209000"]
print(brgy_marayos_parent)
pinamalayan_parent = [loc for loc in BARANGAY_FLAT if loc["psgc_id"]=="1705200000"]
print(pinamalayan_parent)
oriental_mindoro_parent = [loc for loc in BARANGAY_FLAT if loc["psgc_id"]=="1700000000"]
print(oriental_mindoro_parent)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "barangay",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "philippines, geography, barangay, region",
"author": "bendlikeabamboo",
"author_email": "manuelb@hawitsu.xyz",
"download_url": "https://files.pythonhosted.org/packages/09/9a/a032f807366162f1ee19427b4fb2ad47094da452e8413676f133c73905a5/barangay-0.3.1.tar.gz",
"platform": null,
"description": "# barangay\n[<p style=\"text-align:center;\">](https://pypi.org/project/barangay/) [](https://opensource.org/licenses/MIT) [](https://pepy.tech/projects/barangay) [](https://github.com/bendlikeabamboo/barangay/actions/workflows/publish.yaml)<p>\n<p>\n\nPhilippines Standard Geographic Code (PSGC) 2025 Python package for Philippine regions, \nprovinces, cities, municipalities, and barangay. Available in JSON, YAML, and Python\ndictionary formats. Latest and updated as of July 2025.\n\n__SOURCE FILE__: [2025-07-08 PSGC Release](https://psa.gov.ph/classification/psgc/node/1684077694) <br>\n__PyPI__: https://pypi.org/project/barangay/ <br>\n__Installation__: `pip install barangay`\n\n## Features\n\n- Comprehensive, up-to-date list of Philippine barangays and their administrative\n hierarchy based on Philippine Standard Geographic Code ([PSGC](https://psa.gov.ph/classification/psgc))\n- Data also available in both JSON and YAML formats under `barangay/`\n- Available in different data models\n - Direct Nested Hierarchical Model\n - Metadata-rich Recursive Hierarchical Model\n - Metadata-rich Flat Model\n- Easy integration with Python projects.\n\n## Installation\n\n```bash\npip install barangay\n```\n\n## Usage\nSample usage in `notebooks/sample_usage.ipynb`\n\n### barangay.BARANGAY: Direct Nested Hierarchical Model\nTraversing `barangay.BARANGAY` is straightforward since it\u2019s a purely nested dictionary\ncomposed of names, with no additional metadata.\n\n```python\nfrom barangay import BARANGAY\n\n# Example lookup process and dictionary traversal\nall_regions = BARANGAY.keys()\n\n# Looking for NCR Cities & Municipalities\nncr_cities_and_municipalities = list(BARANGAY[\"National Capital Region (NCR)\"].keys())\nprint(f\"NCR Cities & Municipalities: {ncr_cities_and_municipalities}\")\n\n# Looking for Municipalities of Cities of Manila\nmunicipalities_of_manila = list(BARANGAY[\"National Capital Region (NCR)\"][\n \"City of Manila\"\n].keys())\nprint(f\"Municipalities of Manila: {municipalities_of_manila}\")\n\n# Looking for Barangays in Binondo\nbrgy_of_binondo = BARANGAY[\"National Capital Region (NCR)\"][\"City of Manila\"][\n \"Binondo\"\n]\nprint(f\"Brgys of Binondo: {brgy_of_binondo}\")\n```\n\nThe provided code demonstrates a simple traversal of the `BARANGAY` nested dictionary.\nThis dictionary, however, has only simple parent-child structure that doesn't fully\nrepresent the complex geographical hierarchy of the Philippines. For example, some\nmunicipalities like __Pateros__ are directly under a region, and certain highly\nurbanized cities (__HUCs__) such as __Tacloban City__ and __Davao City__ are not part of\na province.\n\nThis simplified structure can make it challenging to implement accurate address\nselectors with labeled forms where distinctions between municipalities and cities and\nprovinces are important. To address this, I developed `barangay.BARANGAY_EXTENDED`, a\nmore complex fractal dictionary that accurately mirrors the intricate geographical\ndivisions of the Philippines.\n\n### barangay.BARANGAY_EXTENDED: Metadata-rich Recursive Hierarchical Model\nTraversing `barangay.BARANGAY_EXTENDED` is slightly more involved, as each location\nincludes rich metadata stored in dictionary fields. Instead of simple key-value pairs,\ntraversal involves navigating lists of dictionaries\u2014adding a bit of complexity, but also\nunlocking far greater flexibility and precision. This structure enables more accurate\nmodeling of the Philippines' administrative divisions, making it ideal for applications\nthat require detailed address handling or contextual geographic data.\n\n```python\nfrom barangay import BARANGAY_EXTENDED\nfrom pprint import pprint\n\n# Listing all component locations under Philippines\nphilippine_components = [item[\"name\"] for item in BARANGAY_EXTENDED[\"components\"]]\nprint(\"philippine_components: \")\npprint(philippine_components)\nprint(\"\\n\\n\")\n\n# retrieving National Capital Region (NCR) location data\nncr = [\n item\n for item in BARANGAY_EXTENDED[\"components\"]\n if item[\"name\"] == \"National Capital Region (NCR)\"\n][0]\n\n# Listing all component locations under NCR. In the output, notice tha Pateros is a\n# municipality directly under a region, which is unusual but possible, nonetheless.\nncr_components = [(item[\"name\"], item[\"type\"]) for item in ncr[\"components\"]]\nprint(\"ncr_components\")\npprint(ncr_components)\nprint(\"\\n\\n\")\n\n# Retrieving City of Manila location data\ncity_of_manila = [\n item for item in ncr[\"components\"] if item[\"name\"] == \"City of Manila\"\n][0]\n\n# Listing all component locations under City of Manila\ncity_of_manila_components = [\n (item[\"name\"], item[\"type\"]) for item in city_of_manila[\"components\"]\n]\nprint(\"city_of_manila_components\")\npprint(city_of_manila_components)\nprint(\"\\n\\n\")\n\n# Retrieving Sta Ana location data\nsta_ana = [\n item for item in city_of_manila[\"components\"] if item[\"name\"] == \"Santa Ana\"\n][0]\n\n# Listing all component locations under Santa Ana (which are now the Barangay)\nsanta_ana_components = [\n (item[\"name\"], item[\"type\"]) for item in sta_ana[\"components\"]\n]\nprint(\"santa_ana_components\")\npprint(santa_ana_components)\nprint(\"\\n\\n\")\n```\n\n### barangay.BARANGAY_FLAT: Metadata-rich Flat Model\n\nThe barangay.BARANGAY_FLAT structure offers a fully flattened list of all Philippine\nadministrative units\u2014regions, provinces, cities, municipalities, and barangays\u2014with rich\nmetadata for each entry. This format is ideal for search, filtering, and integration\nwith tabular data workflows such as pandas DataFrames or database imports.\n\n```python\nfrom barangay import BARANGAY_FLAT\n\n\n# Looking for Brgy. Marayos in Mindoro\nbrgy_marayos = [loc for loc in BARANGAY_FLAT if loc[\"name\"]==\"Marayos\"]\nprint(brgy_marayos)\n\n# From here we can now trace its hierarchy by following parent_psgc_id\nbrgy_marayos_parent = [loc for loc in BARANGAY_FLAT if loc[\"psgc_id\"]==\"1705209000\"]\nprint(brgy_marayos_parent)\n\npinamalayan_parent = [loc for loc in BARANGAY_FLAT if loc[\"psgc_id\"]==\"1705200000\"]\nprint(pinamalayan_parent)\n\noriental_mindoro_parent = [loc for loc in BARANGAY_FLAT if loc[\"psgc_id\"]==\"1700000000\"]\nprint(oriental_mindoro_parent)\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Philippines Standard Geographic Code (PSGC) 2025 Python package, JSON, and YAML.",
"version": "0.3.1",
"project_urls": {
"Bug Tracker": "https://github.com/bendlikeabamboo/barangay/issues",
"Documentation": "https://github.com/bendlikeabamboo/barangay/blob/main/README.md",
"Homepage": "https://hawitu.xyz",
"Repository": "https://github.com/bendlikeabamboo/barangay"
},
"split_keywords": [
"philippines",
" geography",
" barangay",
" region"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "414b53d579a3e13a4c83fb22858849d10fa42cfead74e95f35916dc8c2048078",
"md5": "6099124aa32813f5b3097d2df52e2891",
"sha256": "4e93beabf08b1f1656a3e42fe720d52cdafbb97004656c3956ac17d8ff1f7b51"
},
"downloads": -1,
"filename": "barangay-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6099124aa32813f5b3097d2df52e2891",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 2338830,
"upload_time": "2025-08-13T16:28:28",
"upload_time_iso_8601": "2025-08-13T16:28:28.838833Z",
"url": "https://files.pythonhosted.org/packages/41/4b/53d579a3e13a4c83fb22858849d10fa42cfead74e95f35916dc8c2048078/barangay-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "099aa032f807366162f1ee19427b4fb2ad47094da452e8413676f133c73905a5",
"md5": "78f8e1290fd9f97d663ea124c40d8b01",
"sha256": "14998001ca49d01cddae3c63f8b96394df84e85ebff08de7fa8d1165b2bc69f8"
},
"downloads": -1,
"filename": "barangay-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "78f8e1290fd9f97d663ea124c40d8b01",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2121672,
"upload_time": "2025-08-13T16:28:31",
"upload_time_iso_8601": "2025-08-13T16:28:31.037706Z",
"url": "https://files.pythonhosted.org/packages/09/9a/a032f807366162f1ee19427b4fb2ad47094da452e8413676f133c73905a5/barangay-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 16:28:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bendlikeabamboo",
"github_project": "barangay",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "barangay"
}
