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 (~1.1 MB total, ~533 KB compressed data) using TOON format + gzip compression - 87.6% smaller than raw JSON.
• Fast Performance: Efficient data loading with automatic caching. Initial load under 2 seconds, 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: ~1.1 MB total (vs 4.3 MB raw JSON - 74.4% smaller)
• Initialization: ~1.3 seconds for first call (decompresses and caches all data)
• Subsequent Calls: < 1ms (data is cached in memory)
• Memory Usage: ~7 MB after initialization (decompressed data)

The package uses TOON format with gzip compression for optimal size and performance. Data is automatically decompressed on first use and cached for instant access on subsequent calls.

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