@ph-dev-utils/geo

Philippine geo utilities for JavaScript/TypeScript — a representative coordinate for every PSGC city/municipality plus haversine distance, nearest-city, and within-radius helpers. Part of the @ph-dev-utils family.

Bundled dataset is browser-safe (compiled in, no network, no fs). Coordinates are keyed by the same 6-digit PSGC cityMunCode as @ph-dev-utils/core and @ph-dev-utils/postal, so they join cleanly.

npm install @ph-dev-utils/geo

Quick start

import { findCoord, distanceKm, nearestCity, withinRadiusKm, listCoords } from '@ph-dev-utils/geo';

findCoord('072217');             // { name: 'City of Cebu', lat: 10.31, lng: 123.89, ... }
findCoord('Cebu City');          // same — "City of X" / "X City" tolerant

distanceKm('133900', '072217');  // ~570  (Manila → Cebu, km)
distanceKm({ lat: 14.6, lng: 121 }, 'Makati'); // accepts raw {lat,lng} too

nearestCity('133900', 5);        // 5 nearest cities to Manila, nearest first (with distanceKm)
withinRadiusKm('133900', 30);    // every city/municipality within 30 km of Manila

listCoords({ region: '07' });    // all coordinates in Region VII (Central Visayas)

API

| Function | Returns | | --- | --- | | listCoords(filter?) | Coordinate[] — filter by region and/or province (null matches NCR / independent cities) | | findCoord(query) | Coordinate \| null — by 6-digit PSGC code or city name ("City of X" / "X City" tolerant) | | distanceKm(a, b) | number \| null — great-circle km; each arg is {lat,lng} or a code/name | | nearestCity(point, n = 1) | NearbyCoordinate[] — n nearest, nearest first | | withinRadiusKm(point, km) | NearbyCoordinate[] — all within km, nearest first | | META | provenance + license note for the bundled data |

Coordinate

interface Coordinate {
  cityMunCode: string;        // 6-digit PSGC code (joins @ph-dev-utils/core)
  name: string;
  province: string | null;    // 4-digit province code, or null for NCR / independent cities
  region: string;             // 2-digit region code
  lat: number;
  lng: number;
  points: number;             // GeoNames postal points averaged into this centroid
}

interface NearbyCoordinate extends Coordinate {
  distanceKm: number;         // distance from the query point
}

A point argument (nearestCity, withinRadiusKm, either side of distanceKm) is either a { lat, lng } or a string PSGC code / city name resolvable via findCoord.

Data & disclaimer

Each coordinate is a representative point — the mean of the GeoNames postal-code points that map to the city/municipality — intended for distance/proximity work. It is not an official PSA centroid or a survey-grade location. Coordinates are derived from the GeoNames Philippines postal dump (CC BY 4.0); the ZIP → cityMunCode join is reused from @ph-dev-utils/postal and names/provinces/regions from the PSA Q4 2024 PSGC via @ph-dev-utils/core. See NOTICE for attribution.

License

MIT. Bundled coordinate data © GeoNames, CC BY 4.0.