Introduction

Locale is a developer tool for anyone who needs to know Nigeria, geographically at least. Locale’s API shows you all of Nigeria’s regions, states, and local government areas(LGAs).

Locale allows developers to search for information about Nigeria based on the following categories; region, state and local government area(LGAs).

This document will guide you through the various endpoints and functionalities offered by our API.

Base URL

The base URL for all API endpoints is here

Authentication

All requests to the API endpoints require authentication. You need to include an API key in the header of your requests. The API key should be included in a Authorization header called x-API-key.

Example:

x-API-key:  YOUR_API_KEY

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of a request. In case of an error, the response body will contain a JSON object with an error field providing a brief description of the error.

Example:

{
  "error": "Invalid API key"
}

Endpoints

[Region Endpoint]

[This endpoint fetches all the regions of Nigeria and returns as a JSON object]

HTTP Method

[GET]

Endpoint URL

/region

Request Parameters

Request Headers

Response

Success Response

• HTTP Status Code: 200

• Content-Type: application/json

{
  "data": {
    "region": "North-west",
    "states": ["Kaduna", "Kano", "Katsina", "Kebbi", "Sokoto", "Zamfara"],
    "description": "The North-western states are rich in diverse cultures with unique festivals, the region are dominatly engage in agriculture, commerce and trade. The major languages spoken in this region is The hause and fulani language"
    "economicActivities": ["Agriculture", "Commerce", "Trade" "Tourism"]
  }
}

Error Response

• HTTP Status Code: 400, 401, 404, etc.

• Content-Type: application/json

[Provide an example of an error response.]

{
  "error": "Invalid input"
}

[State Endpoint]

[This endpoint fetches all the regions of Nigeria and returns as a JSON object]

HTTP Method

[GET]

Endpoint URL

/region?state=kano

Request Parameters

Request Headers

Response

Success Response

• HTTP Status Code: 200

• Content-Type: application/json

{
  "data": {
    {
    "_id": "64719dda572f74cb897ac368",
    "state": "Delta",
    "description": "Delta State is a vibrant and diverse state located in the southern part of Nigeria. It was created on August 27, 1991, and its capital city is Asaba, while Warri serves as its commercial and industrial hub. The state derives its name from the Niger Delta, as it is situated in the region where the Niger River meets the Atlantic Ocean.Delta State is known for its rich oil and gas reserves, making it a significant contributor to Nigeria's petroleum industry. The state also boasts a diverse economy, with sectors such as agriculture, manufacturing, commerce, and services playing important roles in its development.The state is home to several ethnic groups, including the Urhobo, Itsekiri, Isoko, Ijaw, and Ndokwa, each with its own unique cultural heritage and traditions. This cultural diversity is reflected in the vibrant festivals, music, dance, and cuisine of the region.Delta State offers a range of attractions for visitors. The Niger River and its tributaries provide opportunities for water-based activities such as boating, fishing, and wildlife viewing. The state also has beautiful beaches along its coastline, including the popular Warri and Burutu beaches.",
    "population": "5.6 million",
    "capital": "Asaba",
    "major_dialect": [
      "Igbo",
      "Urhobo",
      "Isoko",
      "Ijaw"
    ],
    "landmass": "18,050 km²",
    "region": "South-South",
    "economic_activities": [
      "Agriculture",
      "Crude oil Extraction"
    ],
    "local_government_areas": [
      "Aniocha North",
      "Aniocha South",
      "Bomadi",
      "Burutu",
      "Ethiope East",
      "Ethiope West",
      "Ika North East",
      "Ika South",
      "Isoko North",
      "Isoko South",
      "Ndokwa East",
      "Ndokwa West",
      "Okpe",
      "Oshimili North",
      "Oshimili South",
      "Sapele",
      "Udu",
      "Ughelli North",
      "Ughelli South",
      "Ukwuani",
      "Uvwie",
      "Warri South West",
      "Patani",
      "Warri North",
      "Warri South"
    ],
    "average_rainfall": "26.8 °C | 80.2 °F",
    "average_temperature": "1331 mm | 52.4 inch",
    "__v": 0
  }
  }
}

Error Response

• HTTP Status Code: 400, 401, 404, etc.

• Content-Type: application/json

[Provide an example of an error response.]

{
  "error": "Invalid input"
}

[LGA Endpoint]

[This endpoint fetches all the regions of Nigeria and returns as a JSON object]

HTTP Method

[GET]

Endpoint URL

/lga

Request Parameters

Request Headers

Response

Success Response

• HTTP Status Code: 200

• Content-Type: application/json

{
  "data": {
    "lga": "Alimosho",
    "state": "Lagos",
    "description": " Alimosho LGA is one of the largest LGAs in Lagos State. It is located in the northeastern part of the state. It is highly populated and comprises several communities, including Egbeda, Ikotun, and Igando. Alimosho has a mix of residential, commercial, and industrial areas.",
    "stateRegion": "Northern Lagos",
    "economicActivities": [
    "Commerce, Trade and Industralization"
     ]
  }
}

Error Response

• HTTP Status Code: 400, 401, 404, etc.

• Content-Type: application/json

[Provide an example of an error response.]

{
  "error": "fail to fetch"
}