phdevutils/geo

Philippine geo utilities — representative coordinates for all PSGC cities/municipalities plus haversine distance, nearest-city, and within-radius helpers. Data from GeoNames (CC BY 4.0). Zero-dependency.

v0.1.0 2026-06-03 06:45 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• geo
• distance
• coordinates
• latitude
• longitude
• geonames
• philippines
• haversine
• filipino
• psgc

README

Philippine geo utilities for PHP — a representative coordinate for every PSGC city/municipality plus haversine distance, nearest-city, and within-radius helpers. PHP companion to the npm package @ph-dev-utils/geo.

Coordinates are keyed by the same 6-digit PSGC cityMunCode as phdevutils/core, so they join cleanly.

composer require phdevutils/geo

Quick start

use PhDevUtils\Geo\Geo;

Geo::findCoord('072217');            // ['name' => 'City of Cebu', 'lat' => 10.31, 'lng' => 123.89, ...]
Geo::findCoord('Cebu City');         // same — "City of X" / "X City" tolerant

Geo::distanceKm('133900', '072217'); // ~570.0  (Manila → Cebu, km)
Geo::distanceKm(['lat' => 14.6, 'lng' => 121.0], 'Makati'); // accepts raw lat/lng too

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

Geo::listCoords(['region' => '07']); // all coordinates in Region VII (Central Visayas)

API

Method	Returns
Geo::listCoords($filter = [])	array of coordinates — filter by region and/or province (null matches NCR / independent cities)
Geo::findCoord($query)	coordinate array or null — by 6-digit PSGC code or city name ("City of X" / "X City" tolerant)
Geo::distanceKm($a, $b)	float or null — great-circle km; each arg is ['lat'=>,'lng'=>] or a code/name
Geo::nearestCity($point, $n = 1)	array — n nearest, nearest first (each with distanceKm)
Geo::withinRadiusKm($point, $km)	array — all within $km, nearest first
Geo::meta()	array — provenance + license note for the bundled data

Each coordinate array: cityMunCode (6-digit PSGC), name, province (4-digit code or null for NCR / independent cities), region (2-digit code), lat (float), lng (float), points (int — GeoNames postal points averaged into the centroid). nearestCity / withinRadiusKm results add a distanceKm (float) key.

A point argument is either a ['lat' => float, 'lng' => float] array or a string PSGC code / city name resolvable via Geo::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 phdevutils/postal and names/provinces/regions from the PSA Q4 2024 PSGC. See the NOTICE file for attribution.

License

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