/nglocations

Open Source REST API that allows users to retrieve information of all states and geopolitical zones in Nigeria

Primary LanguagePHPMIT LicenseMIT

NGLocations

StyleCI Build Status

1. Overview

The NGLocations is an Open Source REST API that allows users to retrieve information of all states and geopolitical zones in Nigeria. Informations include states, cities, local government areas, geopolical zones etc. For an interactive flow and more, visit documentations.

2. Table of Contents

3. Installation

3.1. Run locally

To run app locally, make sure you have PHP >= 7.1.3 and composer installed.

git clone https://github.com/devdbrandy/nglocations.git # or clone your own fork
cd nglocations
composer install
cp .env.example .env
php artisan key:generate

Pre-fill DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD with database credentials. Then run:

php artisan migrate --seed
php artisan serve # spin up server at http://localhost:8000

3.2. Deploy to heroku

Alternatively, you can deploy your own copy of the app using the web-based flow:

Deploy to Heroku

4. Usage

4.1 Get list of states

API endpoint that represents a list of states

  • URL Endpoint: /api/v1/states

  • Method: GET

  • URL Params: None

  • Request Body: None

  • Success Response

    • Code: 200
    • Content:
      [
      {
          "code": "AB",
          "name": "Abia",
          "alias": "abia",
          "href": "http://nglocations.me/api/v1/states/abia"
      }
  ]

  • Usage Sample:

    GET https://nglocations.me/api/v1/states
HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "code": "AB",
        "name": "Abia",
        "alias": "abia",
        "href": "http://nglocations.me/api/v1/states/abia"
    },
    {
        "code": "AD",
        "name": "Adamawa",
        "alias": "adamawa",
        "href": "http://nglocations.me/api/v1/states/adamawa"
    },
]

4.2. Get a single state

API endpoint that represents a single state

  • URL Endpoint: /api/v1/states/{state}

  • Method: GET

  • URL Params:

    Name Type Description
    state string Required. The state alias

  • Request Body: None

  • Success Response

    • Code: 200
    • Content:
      {
      "code": "LA",
      "name": "Lagos",
      "capital": "Ikeja",
      "alias": "lagos",
      "zone": "South-Western",
      "latitude": "6.4530556",
      "longitude": "3.3958333"
  }

  • Error Response

    • Code: 404 Not Found
    • Content:
      {"error": "Resource does not exist"}

  • Usage Sample:

    GET https://nglocations.me/api/v1/states/lagos
HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "LA",
    "name": "Lagos",
    "capital": "Ikeja",
    "alias": "lagos",
    "zone": "South-Western",
    "latitude": "6.4530556",
    "longitude": "3.3958333"
}

4.3. List cities in a state

API endpoint that represents a list of cities in a state

  • URL Endpoint: /api/v1/states/{state}/cities

  • Method: GET

  • URL Params:

    Name Type Description
    state string Required. The state alias

  • Request Body: None

  • Success Response

    • Code: 200
    • Content:
      [
      {
          "name": "Ikeja",
          "alias": "ikeja"
      },
  ]

  • Usage Sample:

    GET https://nglocations.me/api/v1/states/enugu/cities
HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "name": "Enugu",
        "alias": "enugu"
    },
    {
        "name": "Nsukka",
        "alias": "nsukka"
    },
]

4.4. List Local Governament Areas in a state

API endpoint that represents a list of LGAs in a state

  • URL Endpoint: /api/v1/states/{state}/lgas

  • Method: GET

  • URL Params:

    Name Type Description
    state string Required. The state alias

  • Request Body: None

  • Success Response

    • Code: 200
    • Content:
      [
      {
          "name": "Agege",
          "alias": "agege",
          "latitude": "6.4530556",
          "longitude": "3.3958333"
      },
  ]

  • Usage Sample:

    GET https://nglocations.me/api/v1/states/enugu/cities
HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "name": "Agege",
        "alias": "agege",
        "latitude": "6.4530556",
        "longitude": "3.3958333"
    },
    {
        "name": "Ajeromi\/ifelodun",
        "alias": "ajeromiifelodun",
        "latitude": "6.4530556",
        "longitude": "3.3958333"
    },
]

4.4. Get list of Local Governament Areas

API endpoint that represents a list of LGAs

  • URL Endpoint: /api/v1/lgas

  • Method: GET

  • URL Params: None

  • Request Body: None

  • Success Response

    • Code: 200
    • Content:
      [
      {
          "state": "Abia",
          "alias": "abia",
          "lga": {
              "name": "Aba North",
              "alias": "aba-north",
              "href": "http://nglocations.me/api/v1/lgas/aba-north"
          }
      },
  ]

  • Usage Sample:

    GET https://nglocations.me/api/v1/lgas
HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "state": "Abia",
        "alias": "abia",
        "lga": {
            "name": "Aba North",
            "alias": "aba-north",
            "href": "http://nglocations.me/api/v1/lgas/aba-north"
        }
    },
    {
        "state": "Abia",
        "alias": "abia",
        "lga": {
            "name": "Aba South",
            "alias": "aba-south",
            "href": "http://nglocations.me/api/v1/lgas/aba-south"
        }
    },
]

4.4. Get a single Local Government Area

API endpoint that represents a single LGA

  • URL Endpoint: /api/v1/lgas/{lga}

  • Method: GET

  • URL Params:

    Name Type Description
    lga string Required. The lga alias

  • Request Body: None

  • Success Response

    • Code: 200
    • Content:
      {
      "name": "Ikeja",
      "alias": "ikeja",
      "latitude": "6.4530556",
      "longitude": "3.3958333"
  }

  • Error Response

    • Code: 404 Not Found
    • Content:
      {"error": "Resource does not exist"}

  • Usage Sample:

    GET https://nglocations.me/api/v1/lgas/ikeja
HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "Ikeja",
    "alias": "ikeja",
    "latitude": "6.4530556",
    "longitude": "3.3958333"
}

4.5. Get list of zones

API endpoint that represents a list of deopolitical zones

  • URL Endpoint: /api/v1/zones

  • Method: GET

  • URL Params: None

  • Request Body: None

  • Success Response

    • Code: 200
    • Content:
      [
      {
          "code": "NC",
          "name": "North-Central"
      },
  ]

  • Usage Sample:

    GET https://nglocations.me/api/v1/zones
HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "code": "NC",
        "name": "North-Central"
    },
    {
        "code": "NE",
        "name": "North-Eastern"
    },
]

5. Operations

5.1. Custom Querystring Params

Service supports custom querystring parameters with minimal set of operations for including additional fields to response object.

API Endpoint Querystring Result Example
/api/v1/states capital, lgas, cities, total Includes fields /api/v1/states?cities
/api/v1/states/{state} capital Returns state capital /api/v1/states/lagos?capital
/api/v1/lgas/{lga} state Includes field /api/v1/lgas/surulere?state

6. License

The NGLocations REST API is open-sourced software licensed under the MIT license.