/lumen-ph-geography

Provides a library of locations in the Philippines (regions, provinces, and cities/municipalities) that automatically checks the sources, ensuring the data is always updated.

Primary LanguagePHPMIT LicenseMIT

lumen-ph-geography

Simple REST API implemented using Laravel Lumen. A project inspired from hyubs/ph-locations by Hyubs.

Table of contents

About

Provides a library of locations in the Philippines (regions, provinces, and cities/municipalities) that can automatically check the source, ensuring the data is always updated

Sources

ISO 3166 & Wikipedia

Requirements

PHP 7.3 and later.

Usage

Installation Instructions

  1. Run git clone https://github.com/ikmespinoza/lumen-ph-geography.git.
  2. Create a MySQL database for the project:
    • mysql -u root -p, if using Vagrant: mysql -u <username> -p <password>
    • create database <database-name>;
    • \q
  3. From the projects root run cp .env.example .env.
  4. Configure your .env file.
  5. Run composer update from the projects root folder.
  6. From the projects root folder run composer dump-autoload.
  7. From the projects root folder run php artisan db:seed.

Routes

+------+----------------------------------------------------------+--------------------------------+-----------------------------------------+---------+------------+
| Verb | Path                                                     | NamedRoute                     | Controller                              | Action  | Middleware |
+------+----------------------------------------------------------+--------------------------------+-----------------------------------------+---------+------------+
| GET  | /api/regions                                             | regions.index                  | App\Http\Controllers\RegionController   | index   |            |
| GET  | /api/regions/{region}                                    | regions.show                   | App\Http\Controllers\RegionController   | show    |            |
| GET  | /api/regions/{region}/provinces                          | regions.provinces.index        | App\Http\Controllers\ProvinceController | index   |            |
| GET  | /api/regions/{region}/provinces/{province}               | regions.provinces.show         | App\Http\Controllers\ProvinceController | show    |            |
| GET  | /api/regions/{region}/provinces/{province}/cities        | regions.provinces.cities.index | App\Http\Controllers\CityController     | index   |            |
| GET  | /api/regions/{region}/provinces/{province}/cities/{city} | regions.provinces.cities.show  | App\Http\Controllers\CityController     | show    |            |
+------+----------------------------------------------------------+--------------------------------+-----------------------------------------+---------+------------+

Properties

Regions

Property Description ISO 3166
code ISO 3166 ✓
name English name ✓
name_tl Tagalog name ✓
acronym Acronym, often the roman number or acronym of the region ✓
provinces Provinces in the region ✓

ISO 3166

{
  "code": "PH-13",
  "name": "Caraga",
  "name_tl": "Rehiyon ng Karaga",
  "acronym": "XIII",
  "provinces": [
      {
          "code": "PH-AGN",
          "name": "Agusan del Norte",
          "alt_name": null,
          "name_tl": "Hilagang Agusan",
      },
      {
          "code": "PH-AGS",
          "name": "Agusan del Sur",
          "alt_name": null,
          "name_tl": "Timog Agusan",
      },
      {
          "code": "PH-DIN",
          "name": "Dinagat Islands",
          "alt_name": null,
          "name_tl": "Pulo ng Dinagat"
      },
      ...
  ]
}

Provinces

Property Description ISO 3166
code ISO 3166 ✓
name English name ✓
alt_name Alternative name, often its former name ✓
name_tl Tagalog name ✓
region ISO 3166 of the province's region ✓
cities Cities/Municipalities in the province ✓

ISO 3166

{
  "code": "PH-AGN",
  "name": "Agusan del Norte",
  "alt_name": null,
  "name_tl": "Hilagang Agusan",
  "region": {
      "code": "PH-13",
      "name": "Caraga",
      "name_tl": "Rehiyon ng Karaga",
      "acronym": "XIII"
  },
  "cities": [
      {
          "name": "Buenavista",
          "alt_name": null,
          "full_name": "Buenavista",
          "is_capital": false,
          "classification": {
              "code": "Mun",
              "description": "Municipality"
          }
      },
      {
          "name": "Butuan",
          "alt_name": null,
          "full_name": "Butuan City",
          "is_capital": false,
          "classification": {
              "code": "HUC",
              "description": "Highly Urbanized City"
          }
      },
      {
          "name": "Cabadbaran",
          "alt_name": null,
          "full_name": "Cabadbaran City",
          "is_capital": true,
          "classification": {
              "code": "CC",
              "description": "Component City"
          }
      },
      ...
}

Cities and Municipalities

Property Description ISO 3166
name Name ✓
alt_name Alternative name, often its former name ✓
full_name Complete name. For ISO 3166, all cities will have names end with "City". ✓
is_capital Is the city or municipality the capital of the province ✓
classification Classification of the city or municipality (see below) ✓
province ISO 3166 of the city's or municipality's province ✓

ISO 3166

{
  "name": "Bislig",
  "alt_name": null,
  "full_name": "Bislig City",
  "is_capital": false,
  "classification": {
      "code": "CC",
      "description": "Component City"
  },
  "province": {
      "code": "PH-SUR",
      "name": "Surigao del Sur",
      "alt_name": null,
      "name_tl": "Timog Surigaw"
  }
}

Classifications

ISO 3166

Value Description
Mun Municipality
CC Component city
ICC Independent component city
HUC Highly urbanized city

License

Licensed under the MIT License.