README

A comprehensive REST API for the Philippine Standard Geographic Code (PSGC) data, providing access to official administrative divisions of the Philippines including regions, provinces, cities/municipalities, and barangays.

📦 Laravel Package (Recommended)

For existing Laravel projects - Add PSGC functionality to your project:

composer require edeesonopina/laravel-psgc-api

Quick Setup

# Install the package
composer require edeesonopina/laravel-psgc-api

# Run setup script (optional - handles everything automatically)
node vendor/edeesonopina/laravel-psgc-api/scripts/install-package.js

# Start using the API
php artisan serve
# API available at: http://localhost:8000/api/v1/regions

Manual Setup

# Run migrations
php artisan migrate

# Import PSGC data
php artisan psgc:import --regions=database/psgc/data/regions.csv --provinces=database/psgc/data/provinces.csv --city_municipalities=database/psgc/data/city_municipalities.csv --barangays=database/psgc/data/barangays.csv

Customization Options

Publish Controllers (to customize API logic):

php artisan vendor:publish --provider="EdeesonOpina\PsgcApi\Providers\PsgcApiServiceProvider" --tag="psgc-controllers"

Publish Routes (to customize API endpoints):

php artisan vendor:publish --provider="EdeesonOpina\PsgcApi\Providers\PsgcApiServiceProvider" --tag="psgc-routes"

Publish Models (to add custom relationships):

php artisan vendor:publish --provider="EdeesonOpina\PsgcApi\Providers\PsgcApiServiceProvider" --tag="psgc-models"

Package Documentation: PACKAGE_README.md | Installation Guide

🚀 Features

Official PSGC Data: Uses the latest official PSGC data from the Philippine Statistics Authority (PSA) 2025 2Q
Complete Coverage: All 18 regions, 115 provinces, 1,656 cities/municipalities, and 42,011 barangays
RESTful API: Clean, intuitive REST endpoints with pagination
Laravel Framework: Built with Laravel 11 for reliability and performance
Public Access: Free API for public use and digital integration

📋 Requirements

System Requirements

PHP: 8.1 or higher
Laravel: 9.x, 10.x, 11.x, or 12.x
Database: MySQL, PostgreSQL, SQLite, or SQL Server
Node.js: 16.x or higher (for installation script)

PHP Extensions

ext-pdo - Database connectivity
ext-mbstring - String handling
ext-openssl - Security features
ext-tokenizer - Code parsing
ext-xml - XML processing
ext-ctype - Character type checking
ext-json - JSON processing
ext-bcmath - Arbitrary precision mathematics

Laravel Package Requirements

illuminate/support: ^9.0|^10.0|^11.0|^12.0
illuminate/database: ^9.0|^10.0|^11.0|^12.0
illuminate/console: ^9.0|^10.0|^11.0|^12.0

📊 Data Statistics

Regions: 18
Provinces: 115
Cities/Municipalities: 1,656
Barangays: 42,011
Total Records: 43,800

🔗 API Endpoints

Base URL

http://localhost:8000/api/v1

Important: All endpoint parameters use database IDs (not PSGC codes). This makes the API more developer-friendly and consistent with standard REST practices.

Regions

GET /regions - List all regions
GET /regions/{id} - Get specific region by database ID

Query Parameters:

q - Search by name or code (e.g., ?q=manila)

Provinces

GET /provinces - List all provinces
GET /provinces/{id} - Get specific province by database ID

Query Parameters:

q - Search by name or code (e.g., ?q=manila)
region_id - Filter by region ID (e.g., ?region_id=19)

Cities/Municipalities

GET /city-municipalities - List all cities and municipalities
GET /city-municipalities/{id} - Get specific city/municipality by database ID

Query Parameters:

q - Search by name or code (e.g., ?q=manila)
province_id - Filter by province ID (e.g., ?province_id=86)
region_id - Filter by region ID (e.g., ?region_id=19)
type - Filter by type: City or Municipality (e.g., ?type=City)
limit - Limit results (max 1000, e.g., ?limit=50)

Barangays

GET /barangays - List all barangays
GET /barangays/{id} - Get specific barangay by database ID

Query Parameters:

q - Search by name or code (e.g., ?q=malate)
city_municipality_id - Filter by city/municipality ID (e.g., ?city_municipality_id=44)
province_id - Filter by province ID (e.g., ?province_id=86)
region_id - Filter by region ID (e.g., ?region_id=19)
limit - Limit results (max 1000, e.g., ?limit=100)

📝 Response Format

All endpoints return JSON responses directly (no pagination wrapper):

[
  {
    "id": 19,
    "code": "1300000000",
    "name": "National Capital Region (NCR)",
    "short_name": "13",
    "island_group": "",
    "status": "active",
    "deleted_at": null,
    "created_at": "2025-10-06T05:14:41.000000Z",
    "updated_at": "2025-10-06T05:14:41.000000Z"
  }
]

🚀 API Examples

Get All Regions

curl http://localhost:8000/api/v1/regions

Get Specific Region

curl http://localhost:8000/api/v1/regions/19

Get Provinces in NCR

curl http://localhost:8000/api/v1/provinces?region_id=19

Get Cities in a Province

curl http://localhost:8000/api/v1/city-municipalities?province_id=86&limit=10

Get Barangays in Manila

curl http://localhost:8000/api/v1/barangays?city_municipality_id=44&limit=20

Search for Barangays

curl http://localhost:8000/api/v1/barangays?q=malate&limit=5

Get All Cities (Limited)

curl http://localhost:8000/api/v1/city-municipalities?type=City&limit=50

🔄 Migration Guide (v1.0.0 → v1.1.0)

Breaking Changes

⚠️ Important: v1.1.0 contains breaking changes. Existing applications using v1.0.0 will need updates.

1. Endpoint Parameters Changed

# v1.0.0 (Old)
GET /api/v1/regions/{code}          # Used PSGC codes
GET /api/v1/provinces?region_code=1300000000

# v1.1.0 (New)
GET /api/v1/regions/{id}            # Uses database IDs
GET /api/v1/provinces?region_id=19

2. Response Format Changed

// v1.0.0 (Old)
{
  "table": "regions",
  "rows": [...],
  "pagination": {...}
}

// v1.1.0 (New)
[...]  // Direct array, no wrapper

3. New Features Added

Limit Parameter: ?limit=50 for cities and barangays
Publishable Components: Controllers, routes, and models can be customized
Improved Performance: No pagination overhead for small datasets

Migration Steps

Update Package Version:

composer require edeesonopina/laravel-psgc-api:^1.1.0

Update API Calls:
- Replace {code} with {id} in URLs
- Replace region_code with region_id in parameters
- Update response parsing (remove pagination wrapper)
Test Your Application:
- Verify all API endpoints work with new format
- Update frontend code to handle direct JSON arrays

Staying on v1.0.0

If you prefer to stay on the stable v1.0.0:

composer require edeesonopina/laravel-psgc-api:1.0.0

🛠️ Standalone Project Setup

For new Laravel projects - Clone and set up from scratch:

Prerequisites

PHP 8.2+
Composer
MySQL/SQLite
Node.js (for data conversion)

Installation Steps

Clone the repository

git clone https://github.com/EdeesonOpina/laravel-psgc-api.git
cd laravel-psgc-api

Install PHP dependencies
```
composer install
```
Install Node.js dependencies
```
npm install
```

Environment setup

cp .env.example .env
php artisan key:generate

Database setup
```
php artisan migrate
```

Import PSGC data

# Generate CSV files from official PSGC data
node scripts/convert_psgc_to_csv.js

# Import the data
php artisan psgc:import --regions=database/psgc/data/regions.csv --provinces=database/psgc/data/provinces.csv --city_municipalities=database/psgc/data/city_municipalities.csv --barangays=database/psgc/data/barangays.csv

Start the server
```
php artisan serve --port=8000
```

📋 Data Import & Export Commands

Import Command

The psgc:import command provides several options:

php artisan psgc:import [options]

Options:
  --regions=FILE              Path to regions CSV file
  --provinces=FILE            Path to provinces CSV file
  --city_municipalities=FILE  Path to city/municipalities CSV file
  --barangays=FILE            Path to barangays CSV file
  --truncate                  Truncate all PSGC tables before import
  --dry-run                   Validate only (no DB commit)

Examples

# Import all data
php artisan psgc:import --regions=database/psgc/data/regions.csv --provinces=database/psgc/data/provinces.csv --city_municipalities=database/psgc/data/city_municipalities.csv --barangays=database/psgc/data/barangays.csv

# Dry run (validate only)
php artisan psgc:import --regions=database/psgc/data/regions.csv --dry-run

# Truncate and re-import
php artisan psgc:import --truncate --regions=database/psgc/data/regions.csv --provinces=database/psgc/data/provinces.csv --city_municipalities=database/psgc/data/city_municipalities.csv --barangays=database/psgc/data/barangays.csv

Export Command

The psgc:export command allows you to export data from the database back to CSV or JSON files:

php artisan psgc:export [options]

Options:
  --output=DIR              Output directory (default: exports)
  --regions                 Export regions only
  --provinces               Export provinces only
  --city_municipalities     Export cities/municipalities only
  --barangays               Export barangays only
  --all                     Export all data (default)
  --format=FORMAT           Export format: csv or json (default: csv)
  --status=STATUS           Filter by status: active, inactive, or all (default: active)

Export Examples

# Export all data to CSV
php artisan psgc:export

# Export all data to JSON
php artisan psgc:export --format=json

# Export only regions to custom directory
php artisan psgc:export --regions --output=backup

# Export provinces and cities to JSON
php artisan psgc:export --provinces --city_municipalities --format=json

# Export all data including inactive records
php artisan psgc:export --status=all

# Export to specific directory
php artisan psgc:export --output=my-exports --format=csv

🗄️ Database Schema

Regions Table

id - Primary key
code - PSGC code (10 characters)
name - Region name
short_name - Short region code
island_group - Island group (Luzon/Visayas/Mindanao)
status - Status (active/inactive)
deleted_at - Soft delete timestamp
created_at - Creation timestamp
updated_at - Update timestamp

Provinces Table

id - Primary key
code - PSGC code (10 characters)
name - Province name
region_id - Foreign key to regions table
old_name - Previous name (if any)
status - Status (active/inactive)
deleted_at - Soft delete timestamp
created_at - Creation timestamp
updated_at - Update timestamp

City/Municipalities Table

id - Primary key
code - PSGC code (10 characters)
name - City/Municipality name
province_id - Foreign key to provinces table
region_id - Foreign key to regions table
type - Type (City/Municipality)
income_class - Income classification
urban_rural - Urban/Rural classification
old_name - Previous name (if any)
status - Status (active/inactive)
deleted_at - Soft delete timestamp
created_at - Creation timestamp
updated_at - Update timestamp

Barangays Table

id - Primary key
code - PSGC code (10 characters)
name - Barangay name
city_municipality_id - Foreign key to city_municipalities table
province_id - Foreign key to provinces table
region_id - Foreign key to regions table
old_name - Previous name (if any)
status - Status (active/inactive)
deleted_at - Soft delete timestamp
created_at - Creation timestamp
updated_at - Update timestamp

🔄 Data Updates

The PSGC data is updated quarterly by the Philippine Statistics Authority. To update your local data:

Download latest data
```
npm install @jobuntux/psgc@latest
```
Regenerate CSV files
```
node scripts/convert_psgc_to_csv.js
```

Import updated data

php artisan psgc:import --truncate --regions=database/psgc/data/regions.csv --provinces=database/psgc/data/provinces.csv --city_municipalities=database/psgc/data/city_municipalities.csv --barangays=database/psgc/data/barangays.csv

🙏 Acknowledgments

This project would not be possible without the following contributors and resources:

Data Source & Libraries

@jobuntux/psgc - TypeScript-ready NPM package providing up-to-date PSGC data, updated quarterly in sync with PSA's official releases
Philippine Statistics Authority (PSA) - Official source of PSGC data and classifications
Laravel Framework - Robust PHP framework for building reliable APIs

Development Team

Edeeson Opina - Full Stack Web Developer & Project Lead
- Website: https://edeesonopina.vercel.app/
- Responsible for API architecture, data integration, and system implementation

Special Thanks

The Philippine Statistics Authority for maintaining and providing official PSGC data
The open-source community for tools and libraries that made this project possible
All contributors who help maintain the PSGC data accuracy and accessibility

🤝 Contributing

This API is designed for public use and digital integration. Contributions are welcome!

📄 License

This project is open source and available under the MIT License.

📞 Support

For questions or support, please open an issue in the repository or contact the development team.

🏛️ Data Source

This API uses official PSGC data from the Philippine Statistics Authority (PSA):

Source: PSA PSGC 2025 2Q
Update Frequency: Quarterly
Official Website: psa.gov.ph/classification/psgc
Data Package: Powered by @jobuntux/psgc

Note: This API provides the latest official PSGC data for digital integration and public use. The data is maintained according to PSA standards and updated regularly to reflect administrative changes in the Philippines.

edeesonopina / laravel-psgc-api

Maintainers

Details

README

📦 Laravel Package (Recommended)

Quick Setup

Manual Setup

Customization Options

🚀 Features

📋 Requirements

System Requirements

PHP Extensions

Laravel Package Requirements

📊 Data Statistics

🔗 API Endpoints

Base URL

Regions

Provinces

Cities/Municipalities

Barangays

📝 Response Format

🚀 API Examples

Get All Regions

Get Specific Region

Get Provinces in NCR

Get Cities in a Province

Get Barangays in Manila

Search for Barangays

Get All Cities (Limited)

🔄 Migration Guide (v1.0.0 → v1.1.0)

Breaking Changes

1. Endpoint Parameters Changed

2. Response Format Changed

3. New Features Added

Migration Steps

Staying on v1.0.0

🛠️ Standalone Project Setup

Prerequisites

Installation Steps

📋 Data Import & Export Commands

Import Command

Examples

Export Command

Export Examples

🗄️ Database Schema

Regions Table

Provinces Table

City/Municipalities Table

Barangays Table

🔄 Data Updates

🙏 Acknowledgments

Data Source & Libraries

Development Team

Special Thanks

🤝 Contributing

📄 License

📞 Support

🏛️ Data Source