PH-Geolocation

Introduction

PH-Geolocation is a lightweight JavaScript library that provides a simple client-side API for accessing Philippine geolocation data.
It allows developers to easily retrieve information about regions, provinces, cities/municipalities, and barangays.

The data is based on the official Philippine Standard Geographic Code (PSGC). The raw Excel data was cleaned, reformatted, and converted into structured JSON for efficient usage in web applications.
A spreadsheet (PH_GEO.xlsx) version is also included for offline reference.

---

Available Functions

• async getRegions(): Returns {Promise<string[]>} — all regions.
• async getProvincesByRegion(region): Returns {Promise<string[]>} — all provinces in the specified region.
• async getCitiesByProvince(region, province): Returns {Promise<string[]>} — all cities/municipalities in the specified region and province.
• async getBarangaysByCity(region, province, city): Returns {Promise<string[]>} — all barangays in the specified region, province, and city.

All functions automatically load and cache the dataset on first use.

---

How to Use (via CDN)

Include the library directly in your HTML using a <script> tag:

<script src="https://cdn.jsdelivr.net/gh/Zaenalos/PH-Geolocation@refs/heads/main/ph-geo.js"></script>

Example Usage

<script>
  // Retrieve all regions
  PHGeo.getRegions().then((regions) => console.log("Regions:", regions));

  // Retrieve provinces in NCR
  PHGeo.getProvincesByRegion("National Capital Region (NCR)").then(
    (provinces) => console.log("Provinces in NCR:", provinces)
  );

  // Retrieve cities in Metro Manila
  PHGeo.getCitiesByProvince("National Capital Region (NCR)", "Metro Manila").then(
    (cities) => console.log("Cities in Metro Manila:", cities)
  );

  // Retrieve barangays in Adams, Ilocos Norte
  PHGeo.getBarangaysByCity("Region I (Ilocos Region)", "Ilocos Norte", "Adams").then(
    (barangays) => console.log("Barangays in Adams:", barangays)
  );
</script>

---

Spreadsheet Data

In addition to the JSON data used by this library, a spreadsheet version is provided for offline reference and manual lookup:

📂 PH_GEO.xlsx

This file contains the same structured data as the JSON used by the library.

---

Credits

• Dataset Source: Philippine Standard Geographic Code (PSGC)
• Maintainer: Zaenalos

The raw PSGC dataset was cleaned, reformatted, and structured into JSON and Excel formats by the project maintainer for efficient usage.

---

License

This project is licensed under the MIT License.
You are free to use, modify, and distribute this library with attribution.
See the LICENSE file for full details.

---

Contributing (Optional)

Contributions are welcome! You can help by:

• Updating or expanding the dataset.
• Adding new helper functions or methods.
• Fixing bugs or improving documentation.

Please open a pull request or issue in the GitHub repository.