Data Update

Previous

Want to help keep barangay up to date with the latest PSGC masterlist? This guide walks you through the entire data update process from start to finish.

The package uses calendar versioning — a version like v2026.04.13.0 means the data comes from the PSGC release dated 2026-04-13. Every time the Philippine Statistics Authority publishes an updated masterlist, thsis package needs a refresh.

Prerequisites

Before you begin, make sure you have:

  • Git installed
  • A GitHub account

Step 1: Set Up Your Environment

First, fork both repositories on GitHub:

  1. Go to bendlikeabamboo/barangay-data-repository and click Fork.
  2. Go to bendlikeabamboo/barangay and click Fork.

Then clone your forks locally (replace <your-username> with your GitHub username):

# The data repository — where the generated JSON/YAML/Parquet files live
git clone https://github.com/<your-username>/barangay-data-repository

# The main package — the PyPI-distributed library
git clone https://github.com/<your-username>/barangay

Then, set up the development environment inside the barangay package:

cd barangay

# Linux / macOS
./setup.sh

# Windows (PowerShell)
.\setup.ps1

This installs all dependencies and activates the virtual environment so you're ready to go.

Step 2: Check for New PSGC Data

  1. Visit the PSGC page on the PSA website.
  2. Look for the latest release date. Compare it against the current version in the package — you can check this quickly: bash barangay info version
  3. If there's a newer release, note the exact date (e.g., 2026-04-13).
  4. Create a local folder named after that date somewhere convenient (e.g., mkdir ~/2026-04-13)
  5. Download all four items from the latest PSGC release into that folder:
    • Press Release
    • Publication
    • National & Provincial Summary
    • Summary of Changes

Step 3: Parse and Generate New Data Files

3.1 Create feature branches

Open a terminal for each repository and create branches named after the release date:

# In barangay-data-repository
cd barangay-data-repository
git switch -c update/2026-04-13

# In barangay
cd ../barangay
git switch -c update/2026-04-13

3.2 Activate the environment

Make sure you're inside the barangay directory with the virtual environment active:

cd barangay

# Linux / macOS
./setup.sh

# Windows (PowerShell)
.\setup.ps1

3.3 Run the parser

Use the barpar (short for barangay parser) poe task to convert the raw PSGC files into structured data:

poe barpar ../2026-04-13 ../barangay-data-repository

This reads the Excel/PDF files from your download folder and generates JSON, YAML, and Parquet files into a new 2026-04-13/ directory inside barangay-data-repository.

Step 4: Update the Bundled Data

The barangay package ships with a bundled copy of the data so that users get the latest data out of the box — no downloads required.

  1. Copy all files from the newly created folder in barangay-data-repository (e.g., barangay-data-repository/2026-04-13/).
  2. Paste them into barangay's data directory (barangay/data/), replacing all existing files.
  3. Update the version file to reflect the new release date. > This ensures that anyone who installs or updates the package will get the freshest data by default.
  4. (Optional) If you'd like, update the documentation in docs/ to reflect the new version number.

Step 5: Submit Your Changes

Once everything looks good, commit and push in both repositories:

In barangay-data-repository:

cd barangay-data-repository
git add .
git commit -m "Update data to 2026-04-13 PSGC release"
git push -u origin update/2026-04-13

Then open a pull request targeting the main branch at bendlikeabamboo/barangay-data-repository.

In barangay:

cd ../barangay
git add .
git commit -m "Update bundled data to 2026-04-13 PSGC release"
git push -u origin update/2026-04-13

Then open a pull request targeting the main branch at bendlikeabamboo/barangay.

That's It!

Once both PRs are merged and maintainer made a release tag, a new version of the package will be published to PyPI with the updated PSGC data. Thank you for helping keep Philippine geographic data accessible and up to date!

Overview