PH-Address

A lightweight package that provides a comprehensive collection of Philippine geographic data, based on the official Philippine Standard Geographic Code (PSGC).

Features

• Up-to-Date Data: Sourced from the latest PSGC publications.
• Ultra-Lightweight: Highly optimized bundle size (~373 KB dist) using CSV + gzip compression — 40% smaller than the previous TOON-based format.
• Fast Performance: Efficient data loading with automatic caching. Barangay data (42k rows) decompresses and parses in ~39 ms on first call; subsequent calls are nearly instant.
• Fully Typed: Written in TypeScript for a better developer experience with full type definitions.
• Easy to Use: A simple and intuitive API for retrieving regions, provinces, municipalities, and barangays.
• Zero Configuration: Works out of the box in both Node.js and browser environments.

Node.js and Browser Support

This package is a "hybrid" package that supports both CommonJS (require()) and ESM (import) syntax. It is compatible with both Node.js and browser environments out of the box. The data is bundled directly with the code using efficient compression, so it works seamlessly without needing file system access.

Performance Characteristics

• Bundle Size: ~373 KB (dist/index.mjs) — 40% smaller than the previous TOON-based format
• Initialization: ~39 ms for barangays on first call (decompresses and caches all data)
• Subsequent Calls: < 1ms (data is cached in memory)

The package uses CSV with gzip compression for optimal size and parse speed. Data is automatically decompressed on first use and cached for instant access on subsequent calls.

Format Benchmark

Benchmarked on 42,011 barangay rows (20 iterations median):

| Format | Compressed size | Decompress + parse | |---|---|---| | JSON | 586 KB | 81 ms | | TOON (former) | 508 KB | 220 ms | | CSV full | 477 KB | 77 ms | | CSV optimized (current) | 346 KB | 39 ms |

CSV optimized removes columns that are derivable from the 10-digit PSGC code structure, then derives them at load time — smaller payload and less to parse.

Versioning

This package uses a calendar-based versioning scheme: YYYY.Q.P

• YYYY: The year of the PSGC data publication.
• Q: The quarter of the publication (1, 2, 3, or 4).
• P: A patch number for any bug fixes or improvements to the package itself, which resets with each new quarterly release.

For example, version 2025.3.1 means the data is from the 3rd quarter of 2025, with 1 patch release.

Installation

# Using npm
npm install @aivangogh/ph-address

# Using yarn
yarn add @aivangogh/ph-address

# Using pnpm
pnpm add @aivangogh/ph-address

API Reference

You can import all functions from the package:

import {
  getAllRegions,
  getAllProvinces,
  getProvincesByRegion,
  getMunicipalitiesByProvince,
  getBarangaysByMunicipality,
} from "@aivangogh/ph-address";

getAllRegions()

Returns a sorted list of all regions.

Example:

import { getAllRegions } from "@aivangogh/ph-address";

const regions = getAllRegions();
console.log(regions);
/*
[
  { name: 'AUTONOMOUS REGION IN MUSLIM MINDANAO (ARMM)', psgcCode: '1900000000', designation: 'ARMM' },
  { name: 'BICOL REGION', psgcCode: '0500000000', designation: 'REGION V' },
  ...
]
*/

getAllProvinces()

Returns a sorted list of all provinces.

Example:

import { getAllProvinces } from "@aivangogh/ph-address";

const provinces = getAllProvinces();
console.log(provinces);
/*
[
  { name: 'Abra', psgcCode: '1400100000', regionCode: '1400000000' },
  { name: 'Agusan Del Norte', psgcCode: '1600200000', regionCode: '1600000000' },
  ...
]
*/

getProvincesByRegion(regionCode)

Returns a sorted list of provinces within a specific region.

• regionCode (string): The PSGC code of the region.

Example:

import { getProvincesByRegion } from "@aivangogh/ph-address";

// Get all provinces in Region VII (Central Visayas)
const provinces = getProvincesByRegion("0700000000"); 
console.log(provinces);
/*
[
  { name: 'Bohol', psgcCode: '0701200000', regionCode: '0700000000' },
  { name: 'Cebu', psgcCode: '0702200000', regionCode: '0700000000' }
]
*/

getMunicipalitiesByProvince(provinceCode)

Returns a sorted list of municipalities/cities within a specific province.

• provinceCode (string): The PSGC code of the province.

Example:

import { getMunicipalitiesByProvince } from "@aivangogh/ph-address";

// Get all municipalities in Cebu
const municipalities = getMunicipalitiesByProvince("0702200000");
console.log(municipalities);
/*
[
  { name: 'Alcantara', psgcCode: '0702201000', provinceCode: '0702200000' },
  { name: 'Alcoy', psgcCode: '0702202000', provinceCode: '0702200000' },
  ...
]
*/

getBarangaysByMunicipality(municipalityCode)

Returns a sorted list of barangays within a specific municipality or city.

• municipalityCode (string): The PSGC code of the municipality or city.

Note: In the context of this library and the PSGC data, the term "municipality" is used to refer to both municipalities and cities.

Example:

import { getBarangaysByMunicipality } from "@aivangogh/ph-address";

// Get all barangays in Cebu City
const barangays = getBarangaysByMunicipality("0730600000");
console.log(barangays);
/*
[
  { name: 'Adlaon', psgcCode: '0730600001', municipalCityCode: '0730600000' },
  { name: 'Agsungot', psgcCode: '0730600002', municipalCityCode: '0730600000' },
  ...
]
*/

Types

You can import all the necessary types for use in your TypeScript projects.

import type {
  PHRegion,
  PHProvince,
  PHMunicipality,
  PHBarangay
} from "@aivangogh/ph-address";

Data Source

The data is sourced directly from the quarterly publications of the Philippine Statistics Authority (PSA).

License

MIT