Traverse the Hierarchy

Recipe: navigate the PSGC hierarchy with parent, children, ancestors, and get records by region, province, or municipality.

Author

bendlikeabamboo

Overview

Every record exposes resolved-hierarchy fields and .ancestors / .children properties, and the package ships one level view per PSGC level. This recipe moves up, down, and across the hierarchy.

Upward traversal

from barangay import barangays

brgy = barangays.get(name="Tongmageng")
print(brgy.region)       # Bangsamoro Autonomous Region In Muslim Mindanao (BARMM)
print(brgy.province)     # Tawi-Tawi
print([a.name for a in brgy.ancestors])
# ['Sitangkai', 'Tawi-Tawi', 'Bangsamoro Autonomous Region In Muslim Mindanao (BARMM)']

Downward traversal

from barangay import cities

manila = cities.get(name="City of Manila")
print([c.name for c in manila.children[:3]])
# ['Tondo I/II', 'Binondo', 'Quiapo']

By level

Level views

Each PSGC level has a dedicated view on the Database: regions, provinces, hucs, iccs, component_cities, cities (HUC+ICC+component combined), municipalities, submunicipalities, special_geographic_areas, barangays. Every view supports .get(name=...) (raises on no/many matches), .lookup(psgc_id=...) (returns None on miss), iteration, and .to_frame() / .to_dicts().

from barangay import provinces, municipalities

tawi = provinces.lookup("1907000000")          # Tawi-Tawi
sitangkai = municipalities.get(name="Sitangkai")
print(sitangkai.psgc_id)                        # 1907005000

Filter by ancestor

The resolved-hierarchy fields make ancestor filtering a one-liner — but it’s a full scan over the view, so it’s fine for ad-hoc queries and slow for large subsets:

from barangay import barangays

tawi_barangays = [r for r in barangays if r.province == "Tawi-Tawi"]
print(len(tawi_barangays))   # 203

Use pandas for big filters

For anything beyond a few thousand rows, materialize once with to_frame() and let pandas do the filtering:

import barangay

df = barangay.barangays.to_frame()
subset = df[df["province"] == "Tawi-Tawi"]   # vectorized, far faster than a Python loop

Get all children

.children returns the direct descendants of a record. Recurse for a whole subtree:

from barangay import provinces

def descendants(record):
    out = []
    for child in record.children:
        out.append(child)
        out.extend(descendants(child))
    return out

tawi = provinces.get(name="Tawi-Tawi")
print(len(tawi.children))            # 11  (municipalities)
print(len(descendants(tawi)))        # full subtree under Tawi-Tawi