geoph-lite

Lightweight Philippine region, province, city/municipality, and barangay data from the Philippine Standard Geographic Code (PSGC), without map geometry.

Version 2 contains the PSGC hierarchy as of 30 June 2026. It preserves the official parentage of independent and highly urbanized cities, NCR localities, Pateros, and the region-level BARMM municipalities instead of assigning them to synthetic provinces.

Install

npm install @ianlabicani/geoph-lite

geoph-lite is an ESM package for Node.js 20.10 or newer and modern application tools such as Vite, Next.js, React, and Vue.

Address-form API

Every PSGC code is returned as a 10-character string. Use strings in application state so leading zeroes are preserved.

import { philippines } from '@ianlabicani/geoph-lite';

const regions = philippines.regions();
const provinces = await philippines.provinces(regionCode);

// A parent can be a region or a province.
const regionLocalities = await philippines.localities(regionCode);
const provinceLocalities = await philippines.localities(provinceCode);

const barangays = await philippines.barangays(localityCode);

List and search results are shallow summaries:

{
  psgc_code: '0402103000',
  name: 'City of Bacoor',
  type: 'city'
}

type is present only for localities and is either city or municipality.

API reference

| Export or method | Returns | | --- | --- | | regions / philippines.regions() | Immediate summaries for all 18 regions. | | loadRegion(region) / philippines.region(region) | The complete native hierarchy for one region. | | provinces(region) / philippines.provinces(region) | Province summaries for a region. | | localities(parentCode) / philippines.localities(parentCode) | City/municipality summaries directly under a region or province. | | barangays(localityCode) / philippines.barangays(localityCode) | Barangay summaries for a locality. | | findRegions(query) | Case-insensitive region name or code matches. | | findProvinces(region, query) | Case-insensitive province matches within a region. | | findLocalities(parentCode, query) | Case-insensitive locality matches under a region or province. |

Region loaders accept an exact region name or PSGC code. Parent and locality lookups use globally unique PSGC codes. Numeric codes are accepted and left-padded to 10 digits, but strings are preferred.

Unknown codes and incorrect parent types throw descriptive errors rather than returning data from the wrong level.

Full hierarchy and direct JSON imports

import { loadRegion } from '@ianlabicani/geoph-lite';

const ncr = await loadRegion('1300000000');
console.log(ncr.localities);

The returned value uses the native data shape:

{
  psgc_code: '1300000000',
  name: 'National Capital Region (NCR)',
  provinces: [],
  localities: [/* cities and municipalities with barangays */]
}

Known generated region files can also be imported directly:

import ncr from '@ianlabicani/geoph-lite/regions/1300000000-national-capital-region-ncr.json' with { type: 'json' };

The complete dataset is split by region and loaded lazily. Importing the package loads only the small region catalog and parent index; the full hierarchy for a region loads when it is requested.

Working example

The repository includes a plain HTML address form that handles both Region → Locality → Barangay and Region → Province → Locality → Barangay:

npm run example

Open http://localhost:4173. Browsers block module imports when the example is opened directly with file://.

Data source and licensing

The administrative data is a Second Quarter 2026 snapshot of the Philippine Statistics Authority Philippine Standard Geographic Code, as of 30 June 2026.

Package code is distributed under the MIT License. The PSGC data has separate attribution and licensing information in DATA_LICENSE.md.

This package contains administrative lookup data only. It has no geometry or coordinates and is not suitable for maps, routing, reverse geocoding, or spatial analysis.