First Lookup

A 5-minute end-to-end tour of the barangay package: browse views, look up records, traverse hierarchy, fuzzy search, validate addresses, export to pandas, and switch historical versions (Python + CLI).
Author

bendlikeabamboo

A 5-minute end-to-end tour of what barangay can do. Assumes you have already installed the package.

Browse admin levels

Pre-built views give direct access to every PSGC administrative level.

from barangay import regions, provinces, municipalities, cities, barangays

print(regions)     # <PSGC region database: 18 records>
print(provinces)   # <PSGC province database: 82 records>
print(barangays)   # <PSGC barangay database: 42010 records>
barangay info stats
Model Barangay Count
Basic (nested) 42010
Flat (list) 42010
Extended (recursive) 42010

Look up a record

brgy = barangays.get(name="Tongmageng")
print(brgy.region)    # Bangsamoro Autonomous Region In Muslim Mindanao (BARMM)
print(brgy.province)  # Tawi-Tawi
print(brgy.psgc_id)   # 1907005010
barangay search Tongmageng

Pandas export

from barangay import barangays

df = barangays.to_frame()
print(df.columns.tolist())
# ['name', 'type', 'psgc_id', 'parent_psgc_id', 'nicknames', 'extensions',
#  'region', 'province', 'highly_urbanized_city', 'independent_component_city',
#  'component_city', 'municipality', 'submunicipality',
#  'special_geographic_area', 'barangay']
print(df.shape)  # (42010, 15)
barangay export --model flat --format json --output data.json

Hierarchy traversal

brgy = barangays.get(name="Tongmageng")
print(brgy.parent)     # <municipality: Sitangkai (1907005000)>
print(brgy.ancestors)  # [municipality, province, region]

manila = cities.get(name="City of Manila")
for child in manila.children[:3]:
    print(child)  # <submunicipality: Tondo I/II ...>, <submunicipality: Binondo ...>, ...

Address validation

from barangay import validate, validate_many

v = validate("Tongmageng, Sitangkai, Tawi-Tawi")
print(v.valid, v.matched_name, v.score)  # True Tongmageng 100.0

results = validate_many(["Tongmageng, Sitangkai, Tawi-Tawi", "Nonexistent Place"])
for r in results:
    print(f"{r.input!r} -> {'valid' if r.valid else 'invalid'}")
barangay batch validate addresses.txt