psgc

Philippine Standard Geographic Code (PSGC) Python package with latitude/longitude coordinates, spatial queries, fuzzy search, reverse geocoding, address parsing, and GeoJSON export.

42,010 barangays, 1,656 cities/municipalities/sub-municipalities, 82 official provinces, 20 package parent groups, and 18 regions with 2024 Census population data. Based on the official PSA PSGC Q1 2026 release.

Live Demo

Quick Start

pip install psgc

import psgc

place = psgc.get("Ermita")
place.coordinate        # Coordinate(14.5838, 120.9823)
place.coordinate_source # 'child_area_weighted_centroid'
place.parent            # Province('National Capital Region (NCR)', ...)
place.breadcrumb        # ['National Capital Region (NCR)', 'Ermita']

Requirements: Python 3.10+

Features

Installation

# Core package (search, data, address parsing)
pip install psgc

# With spatial queries (nearest, radius, reverse geocode)
pip install psgc[geo]

# With CLI
pip install psgc[cli]

# Everything
pip install psgc[all]

Optional Extras

Versioning

psgc uses date-based PEP 440 versions because the bundled PSGC data release is the main compatibility signal.

• Format: YYYY.M.D.N
• YYYY.M.D is the PSGC data release date, also exposed as psgc.__data_date__.
• N increments for package, parser, or data-correction releases against the same data date.
• Current package version: 2026.4.13.0

Check the installed version with:

import psgc

psgc.__version__    # '2026.4.13.0'
psgc.__data_date__  # '2026-04-13'

Release notes live in CHANGELOG.md. Maintainer release steps live in RELEASING.md.

Python API

Look Up a Place

import psgc

# By name (fuzzy matched)
place = psgc.get("Ermita")
place.name          # 'Ermita'
place.coordinate    # Coordinate(14.5838, 120.9823)
place.parent        # Province('National Capital Region (NCR)', ...)
place.breadcrumb    # ['National Capital Region (NCR)', 'Ermita']
place.coordinate_source  # 'child_area_weighted_centroid'

# By PSGC code (instant O(1) lookup)
place = psgc.get("1380608000")

# Check if a place exists
psgc.exists("Ermita")      # True
psgc.exists("Xanadu")      # False

# Ambiguous names raise with helpful guidance
try:
    psgc.get("Barangay 1 (Poblacion)")
except psgc.AmbiguousLookupError as e:
    print(e.matches)  # list of matching places to choose from
    # Disambiguate:
    psgc.get("Barangay 1 (Poblacion), Legazpi City")

Fuzzy Search

results = psgc.search("Cebu")

results[0].name     # 'Cebu'
results[0].score    # 100.0
results[0].level    # 'province'
results[0].place    # Province('Cebu', ...) -- the actual object

# From the result, navigate the hierarchy
results[0].place.children   # list of cities in Cebu

# Custom search with hooks and threshold
results = psgc.search(
    "Sebu",
    n=5,
    match_hooks=["city"],     # search cities only
    threshold=70.0,
    phonetic=True,            # Filipino phonetic matching
)

Autocomplete

results = psgc.suggest("mak", limit=5)
# [{"name": "Makati City", "psgc_code": "...", "level": "city"}, ...]

Spatial Queries

Requires pip install psgc[geo].

# Nearest barangays to a GPS point
results = psgc.nearest(14.5995, 120.9842, n=5)
results[0].place        # Barangay('Barangay 394', ...)
results[0].distance_km  # 0.108

# All barangays within 5 km
results = psgc.within_radius(14.5995, 120.9842, radius_km=5)

# Straight-line distance between two places (not driving distance)
psgc.distance("Ermita, Manila", "Cebu City")  # 562.266 km (as the crow flies)

# Reverse geocode: coordinates -> barangay
result = psgc.reverse_geocode(14.5547, 121.0244)
result.barangay   # 'Poblacion'
result.city       # 'Makati City'
result.province   # 'NCR, Third District'
result.place      # Barangay('Poblacion', ...) -- full object

Data Access

# All 18 regions
for r in psgc.regions:
    print(f"{r.name} ({r.island_group.value})")
    print(f"  Lat: {r.coordinate.latitude}, Lng: {r.coordinate.longitude}")

# Hierarchical navigation
brgy = psgc.barangays[0]
brgy.parent                    # parent City
brgy.parent.parent             # parent Province
brgy.parent.parent.parent      # parent Region
brgy.siblings[:3]              # other barangays in same city
brgy.is_urban                  # True/False

# Cities with sub-municipalities (e.g. Manila)
manila = psgc.get("Manila")
manila.children                # 897 barangays (walks through sub-municipalities)
manila.sub_municipalities      # [Tondo I/II, Binondo, Sampaloc, ...]

# Flat denormalized list (ideal for filtering)
urban_ncr = [b for b in psgc.flat if b.region_name and "NCR" in b.region_name and b.urban_rural == "U"]

# Recursive tree
for region_node in psgc.tree:
    for province_node in region_node.components:
        print(f"  {province_node.name}: {len(province_node.components)} cities")

Address Parsing

result = psgc.parse_address("123 Rizal St., Brgy. San Antonio, Makati City")
result.street       # '123 Rizal St.'
result.barangay     # 'San Antonio'
result.city         # 'Makati City'
result.province     # 'NCR, Third District'
result.confidence   # 0.95

ZIP Code Lookup

info = psgc.zip_lookup("1000")
info["area"]      # 'Ermita, Manila'
info["city"]      # 'City of Manila'

PSGC Code Validation

is_valid, reason = psgc.validate("1380608000")
# (True, "Valid city/municipality code")

Export

# GeoJSON with coordinates
geojson = psgc.to_geojson(level="barangay", region="NCR", as_dict=True)

# CSV with lat/lng columns
psgc.to_csv(level="barangay", output="barangays.csv")

Logging

# Silent by default. Enable for debugging:
# Enable verbose output:
psgc.setup_logging(verbose=True)

# Or via environment variable:
# PSGC_VERBOSE=true python my_script.py

CLI

Requires pip install psgc[cli].

# Look up
psgc search "Cebu" -n 3
psgc suggest "makat"

# Spatial (requires psgc[geo])
psgc nearest 14.5995 120.9842 -n 5
psgc within-radius 14.5995 120.9842 --km 10
psgc reverse-geocode 14.5833 120.9822
psgc distance "Ermita, Manila" "Cebu City"

# Address parsing
psgc parse "Brgy. San Antonio, Makati City"

# Export
psgc export --format geojson --level barangay --region "NCR" -o ncr.geojson
psgc export --format csv --level city -o cities.csv

# Info
psgc info stats
psgc info version
psgc validate 1380608000
psgc zip 1000

Data Sources

Coordinates: Every record with coordinates also has a coordinate_source value. Barangays are classified as:

• hdx_exact_2023: current PSGC code matched a November 2023 HDX/NAMRIA polygon.
• hdx_correspondence_2023: current PSGC code was matched to an HDX polygon using the PSA correspondence code.
• hdx_name_parent_2023: current PSGC code was matched to a unique HDX polygon by barangay name within the same parent city/municipality.
• merged_hdx_area_weighted_2026q1: Q1 2026 merge applied from multiple HDX polygons.
• fallback_unverified: no HDX polygon match is available; coordinates are retained only as low-confidence display points.

Parent city, province, package-group, and region coordinates are recomputed from child barangay coordinates using area-weighted centroids. Package parent groups are used for NCR, highly urbanized cities, and PSA special groupings so independent cities are no longer attached to unrelated provinces. See CHANGELOG.md for release-specific changes.

Performance

Known Limitations

Disclaimer

This is a community-maintained open-source project. It is not affiliated with, endorsed by, or officially connected to the Philippine Statistics Authority (PSA) or NAMRIA.

Data Attribution

• PSGC data (names, codes, population, classifications): Philippine Statistics Authority. Public information under the Philippine Statistical Act of 2013 (RA 10625).
• Administrative boundary coordinates and area: OCHA HDX Philippines Subnational Administrative Boundaries, sourced from PSA and NAMRIA. Licensed under CC BY-IGO.
• ZIP code supplement: Community ZIP-code data from simonpangan/Philippines-Zip-Codes, with existing curated package entries preserved for backwards-compatible display strings. ZIP codes are not part of the official PSGC.

License

MIT