{"id":22404425,"url":"https://github.com/devdbrandy/nglocations","last_synced_at":"2025-03-27T01:16:42.215Z","repository":{"id":48359847,"uuid":"153914406","full_name":"devdbrandy/nglocations","owner":"devdbrandy","description":"Open Source REST API that allows users to retrieve information of all states and geopolitical zones in Nigeria","archived":false,"fork":false,"pushed_at":"2021-07-30T04:15:31.000Z","size":506,"stargazers_count":0,"open_issues_count":13,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-02-01T06:42:00.377Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://nglocations.herokuapp.com/docs","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devdbrandy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-20T14:33:45.000Z","updated_at":"2020-05-05T08:40:16.000Z","dependencies_parsed_at":"2022-08-20T05:00:53.053Z","dependency_job_id":null,"html_url":"https://github.com/devdbrandy/nglocations","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdbrandy%2Fnglocations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdbrandy%2Fnglocations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdbrandy%2Fnglocations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdbrandy%2Fnglocations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devdbrandy","download_url":"https://codeload.github.com/devdbrandy/nglocations/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245761303,"owners_count":20667895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-05T10:13:02.650Z","updated_at":"2025-03-27T01:16:42.200Z","avatar_url":"https://github.com/devdbrandy.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eNGLocations\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.styleci.io/repos/153914406\"\u003e\n        \u003cimg src=\"https://github.styleci.io/repos/153914406/shield?branch=develop\" alt=\"StyleCI\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://app.codeship.com/projects/07f963d0-b856-0136-e4a9-6ec9e9b18678\"\u003e\n        \u003cimg src=\"https://app.codeship.com/projects/07f963d0-b856-0136-e4a9-6ec9e9b18678/status?branch=develop\" alt=\"Build Status\"\u003e\n    \u003c/a\u003e\n    \u003c!--\u003ca href='https://coveralls.io/github/devdbrandy/nglocations?branch=develop'\u003e\n        \u003cimg src='https://coveralls.io/repos/github/devdbrandy/nglocations/badge.svg?branch=develop'\n            alt='Coverage Status'\u003e\n    \u003c/a\u003e--\u003e\n    \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\"\u003e\n    \u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/maintenance/yes/2018.svg\"\u003e\n\u003c/p\u003e\n\n## 1. Overview\nThe NGLocations is an Open Source REST API that allows users to retrieve information of all states and geopolitical zones in Nigeria. Informations include [states](#41-get-all-states), [cities](#43-list-cities-in-a-state), [local government areas](#44-list-local-governament-areas-in-a-state), [geopolical zones](#) etc. For an interactive flow and more, [visit documentations](https://nglocations.herokuapp.com).\n\n## 2. Table of Contents\n\n- [1. Overview](#1-overview)\n- [2. Table of Contents](#2-table-of-contents)\n- [3. Installation](#3-installation)\n    - [3.1. Run locally](#31-run-locally)\n    - [3.2. Deploy to heroku](#32-deploy-to-heroku)\n- [4. Usage](#4-usage)\n    - [4.1 Get list of states](#41-get-list-of-states)\n    - [4.2. Get a single state](#42-get-a-single-state)\n    - [4.3. List cities in a state](#43-list-cities-in-a-state)\n    - [4.4. List Local Governament Areas in a state](#44-list-local-governament-areas-in-a-state)\n    - [4.4. Get list of Local Governament Areas](#44-get-list-of-local-governament-areas)\n    - [4.4. Get a single Local Government Area](#44-get-a-single-local-government-area)\n    - [4.5. Get list of zones](#45-get-list-of-zones)\n- [5. Operations](#5-operations)\n    - [5.1. Custom Querystring Params](#51-custom-querystring-params)\n- [6. License](#6-license)\n\n## 3. Installation\n\n### 3.1. Run locally\nTo run app locally, make sure you have `PHP \u003e= 7.1.3` and `composer` installed.\n```bash\ngit clone https://github.com/devdbrandy/nglocations.git # or clone your own fork\ncd nglocations\ncomposer install\ncp .env.example .env\nphp artisan key:generate\n```\n\nPre-fill `DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD` with database credentials. Then run:\n```bash\nphp artisan migrate --seed\nphp artisan serve # spin up server at http://localhost:8000\n```\n\n### 3.2. Deploy to heroku\n\nAlternatively, you can deploy your own copy of the app using the web-based flow:\n\n[![Deploy to Heroku](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy)\n\n## 4. Usage\n\n### 4.1 Get list of states\n\nAPI endpoint that represents a list of states\n- **URL Endpoint:** `/api/v1/states`\n- **Method:** `GET`\n- **URL Params:** `None`\n- **Request Body:** `None`\n- **Success Response**\n  - **Code:** `200`\n  - **Content:**\n  ```http\n    [\n        {\n            \"code\": \"AB\",\n            \"name\": \"Abia\",\n            \"alias\": \"abia\",\n            \"href\": \"http://nglocations.me/api/v1/states/abia\"\n        }\n    ]\n  ```\n- **Usage Sample:**\n\n    ```http\n    GET https://nglocations.me/api/v1/states\n    HTTP/1.1\n    Accept: application/json\n\n    HTTP/1.1 200 OK\n    Content-Type: application/json\n\n    [\n        {\n            \"code\": \"AB\",\n            \"name\": \"Abia\",\n            \"alias\": \"abia\",\n            \"href\": \"http://nglocations.me/api/v1/states/abia\"\n        },\n        {\n            \"code\": \"AD\",\n            \"name\": \"Adamawa\",\n            \"alias\": \"adamawa\",\n            \"href\": \"http://nglocations.me/api/v1/states/adamawa\"\n        },\n    ]\n    ```\n\n### 4.2. Get a single state\n\nAPI endpoint that represents a single state\n- **URL Endpoint:** `/api/v1/states/{state}`\n- **Method:** `GET`\n- **URL Params:** \n\n    Name | Type | Description\n    ----------|------|------------\n    `state` | `string` | **Required.** The state alias\n\n- **Request Body:** `None`\n- **Success Response**\n  - **Code:** `200`\n  - **Content:**\n  ```http\n    {\n        \"code\": \"LA\",\n        \"name\": \"Lagos\",\n        \"capital\": \"Ikeja\",\n        \"alias\": \"lagos\",\n        \"zone\": \"South-Western\",\n        \"latitude\": \"6.4530556\",\n        \"longitude\": \"3.3958333\"\n    }\n  ```\n- **Error Response**\n  - **Code:** `404 Not Found`\n  - **Content:**\n  \n  ```http\n    {\"error\": \"Resource does not exist\"}\n  ```\n- **Usage Sample:**\n\n    ```http\n    GET https://nglocations.me/api/v1/states/lagos\n    HTTP/1.1\n    Accept: application/json\n\n    HTTP/1.1 200 OK\n    Content-Type: application/json\n\n    {\n        \"code\": \"LA\",\n        \"name\": \"Lagos\",\n        \"capital\": \"Ikeja\",\n        \"alias\": \"lagos\",\n        \"zone\": \"South-Western\",\n        \"latitude\": \"6.4530556\",\n        \"longitude\": \"3.3958333\"\n    }\n    ```\n\n### 4.3. List cities in a state\n\nAPI endpoint that represents a list of cities in a state\n- **URL Endpoint:** `/api/v1/states/{state}/cities`\n- **Method:** `GET`\n- **URL Params:** \n\n    Name | Type | Description\n    ----------|------|------------\n    `state` | `string` | **Required.** The state alias\n\n- **Request Body:** `None`\n- **Success Response**\n  - **Code:** `200`\n  - **Content:**\n  ```http\n    [\n        {\n            \"name\": \"Ikeja\",\n            \"alias\": \"ikeja\"\n        },\n    ]\n  ```\n- **Usage Sample:**\n\n    ```http\n    GET https://nglocations.me/api/v1/states/enugu/cities\n    HTTP/1.1\n    Accept: application/json\n\n    HTTP/1.1 200 OK\n    Content-Type: application/json\n\n    [\n        {\n            \"name\": \"Enugu\",\n            \"alias\": \"enugu\"\n        },\n        {\n            \"name\": \"Nsukka\",\n            \"alias\": \"nsukka\"\n        },\n    ]\n    ```\n\n### 4.4. List Local Governament Areas in a state\n\nAPI endpoint that represents a list of LGAs in a state\n- **URL Endpoint:** `/api/v1/states/{state}/lgas`\n- **Method:** `GET`\n- **URL Params:** \n\n    Name | Type | Description\n    ----------|------|------------\n    `state` | `string` | **Required.** The state alias\n\n- **Request Body:** `None`\n- **Success Response**\n  - **Code:** `200`\n  - **Content:**\n  ```http\n    [\n        {\n            \"name\": \"Agege\",\n            \"alias\": \"agege\",\n            \"latitude\": \"6.4530556\",\n            \"longitude\": \"3.3958333\"\n        },\n    ]\n  ```\n- **Usage Sample:**\n\n    ```http\n    GET https://nglocations.me/api/v1/states/enugu/cities\n    HTTP/1.1\n    Accept: application/json\n\n    HTTP/1.1 200 OK\n    Content-Type: application/json\n\n    [\n        {\n            \"name\": \"Agege\",\n            \"alias\": \"agege\",\n            \"latitude\": \"6.4530556\",\n            \"longitude\": \"3.3958333\"\n        },\n        {\n            \"name\": \"Ajeromi\\/ifelodun\",\n            \"alias\": \"ajeromiifelodun\",\n            \"latitude\": \"6.4530556\",\n            \"longitude\": \"3.3958333\"\n        },\n    ]\n    ```\n\n### 4.4. Get list of Local Governament Areas\n\nAPI endpoint that represents a list of LGAs\n- **URL Endpoint:** `/api/v1/lgas`\n- **Method:** `GET`\n- **URL Params:** `None`\n- **Request Body:** `None`\n- **Success Response**\n  - **Code:** `200`\n  - **Content:**\n  ```http\n    [\n        {\n            \"state\": \"Abia\",\n            \"alias\": \"abia\",\n            \"lga\": {\n                \"name\": \"Aba North\",\n                \"alias\": \"aba-north\",\n                \"href\": \"http://nglocations.me/api/v1/lgas/aba-north\"\n            }\n        },\n    ]\n  ```\n- **Usage Sample:**\n\n    ```http\n    GET https://nglocations.me/api/v1/lgas\n    HTTP/1.1\n    Accept: application/json\n\n    HTTP/1.1 200 OK\n    Content-Type: application/json\n\n    [\n        {\n            \"state\": \"Abia\",\n            \"alias\": \"abia\",\n            \"lga\": {\n                \"name\": \"Aba North\",\n                \"alias\": \"aba-north\",\n                \"href\": \"http://nglocations.me/api/v1/lgas/aba-north\"\n            }\n        },\n        {\n            \"state\": \"Abia\",\n            \"alias\": \"abia\",\n            \"lga\": {\n                \"name\": \"Aba South\",\n                \"alias\": \"aba-south\",\n                \"href\": \"http://nglocations.me/api/v1/lgas/aba-south\"\n            }\n        },\n    ]\n    ```\n\n### 4.4. Get a single Local Government Area\n\nAPI endpoint that represents a single LGA\n- **URL Endpoint:** `/api/v1/lgas/{lga}`\n- **Method:** `GET`\n- **URL Params:** \n\n    Name | Type | Description\n    ----------|------|------------\n    `lga` | `string` | **Required.** The lga alias\n\n- **Request Body:** `None`\n- **Success Response**\n  - **Code:** `200`\n  - **Content:**\n  ```http\n    {\n        \"name\": \"Ikeja\",\n        \"alias\": \"ikeja\",\n        \"latitude\": \"6.4530556\",\n        \"longitude\": \"3.3958333\"\n    }\n  ```\n- **Error Response**\n  - **Code:** `404 Not Found`\n  - **Content:**\n  \n  ```http\n    {\"error\": \"Resource does not exist\"}\n  ```\n- **Usage Sample:**\n\n    ```http\n    GET https://nglocations.me/api/v1/lgas/ikeja\n    HTTP/1.1\n    Accept: application/json\n\n    HTTP/1.1 200 OK\n    Content-Type: application/json\n\n    {\n        \"name\": \"Ikeja\",\n        \"alias\": \"ikeja\",\n        \"latitude\": \"6.4530556\",\n        \"longitude\": \"3.3958333\"\n    }\n    ```\n\n### 4.5. Get list of zones\n\nAPI endpoint that represents a list of deopolitical zones\n- **URL Endpoint:** `/api/v1/zones`\n- **Method:** `GET`\n- **URL Params:** `None`\n- **Request Body:** `None`\n- **Success Response**\n  - **Code:** `200`\n  - **Content:**\n  ```http\n    [\n        {\n            \"code\": \"NC\",\n            \"name\": \"North-Central\"\n        },\n    ]\n  ```\n- **Usage Sample:**\n\n    ```http\n    GET https://nglocations.me/api/v1/zones\n    HTTP/1.1\n    Accept: application/json\n\n    HTTP/1.1 200 OK\n    Content-Type: application/json\n\n    [\n        {\n            \"code\": \"NC\",\n            \"name\": \"North-Central\"\n        },\n        {\n            \"code\": \"NE\",\n            \"name\": \"North-Eastern\"\n        },\n    ]\n    ```\n\n## 5. Operations\n\n### 5.1. Custom Querystring Params\nService supports custom querystring parameters with minimal set of operations for including additional fields to response object.\n\nAPI Endpoint | Querystring | Result | Example\n-------------|-------------|----------|--------\n`/api/v1/states` | `capital`, `lgas`, `cities`, `total` | Includes fields | [/api/v1/states?cities](#41-get-list-of-states)\n`/api/v1/states/{state}` | `capital` | Returns state capital | [/api/v1/states/lagos?capital](#42-get-a-single-state)\n`/api/v1/lgas/{lga}` | `state` | Includes field | [/api/v1/lgas/surulere?state](#44-get-a-single-local-government-area)\n\n## 6. License\n\nThe NGLocations REST API is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevdbrandy%2Fnglocations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevdbrandy%2Fnglocations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevdbrandy%2Fnglocations/lists"}