barangay — Philippine PSGC Python Package

Offline Python package for the Philippine Standard Geographic Code (PSGC): 42,010 barangays, municipalities, cities, provinces, and regions with fuzzy search and address validation. No API calls needed.
Author

bendlikeabamboo

Python package for accessing Philippine Standard Geographic Code (PSGC) data covering all 42,010 barangays, 1,493 municipalities, 150 cities, 82 provinces, and 18 regions — offline, no API calls needed.

PyPI version PyPI Downloads License: MIT Release Badge

Get started in seconds

pip install barangay
from barangay import barangays, search_fuzzy

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

2for r in search_fuzzy("Tongmagen, Tawi-Tawi"):
    print(f"{r.name} ({r.psgc_id}) — score: {r.score}")
1
.get(name=...) returns a typed EnrichedRecord with resolved hierarchy fields (.region, .province, .municipality, …).
2
search_fuzzy() returns typed SearchResult objects ranked by a fuzzy score — tolerant of misspellings and non-standard formats.

New here? Walk through the First Lookup tour (Python + CLI) in five minutes.

Choose your path

Data analyst / scientist ›

Export to CSV / pandas · Bulk barangay lookup

App / backend developer ›

Address validation · Database API tutorial

CLI / ops / non-Python ›

CLI reference · Geocode batch files

Researcher / GIS / academic ›

Concepts · Data dictionary

Migrator (legacy code) ›

Migrate from the legacy API

Contributor / maintainer ›

Community

Features

  • Bundled PSGC Dataset: Native access to PSGC data, no database or API calls needed
  • Hierarchy Traversal: Navigate parent, children, and ancestors of any admin division
  • Direct Pandas Export: to_frame() and to_dicts() for immediate DataFrame access
  • Address Validation: validate() and validate_many() for automated address checking
  • Fuzzy Search: Fast, customizable fuzzy matching with typed SearchResult objects
  • Historical PSGC Data: On-demand access to previous PSGC releases by date
  • Multiple Data Models: Basic (nested), Extended (recursive), and Flat (list)
  • Plug-in System: Enrich PSGC data with custom extensions via plug-ins (CSV, JSON, Parquet)

Data Version

Current data version: 2026-04-13 (April 13 2026 PSGC masterlist)

WarningDeprecation Notice

BARANGAY/BARANGAY_EXTENDED/BARANGAY_FLAT dict aliases and search() are deprecated and will be removed in 2027.X.X.X. Use the Database API for new code (e.g. barangays.get(name="Tongmageng"), search_fuzzy("query")). See Migrate from the legacy API.