States & Cities.

Providing a public API for states and cities in Nigeria

---

About.

It just a simple API that lets you get a list of states, cities and local government areas in Nigeria. In JSON duh. It's made for the developer who wants to make a simple drop down list of Nigerian locations for any app in any language. (It's also not limited to that developer's use case).

It's built in Python with Flask using a local JSON dataset.

URI and Versioning.

We hope to improve this API over time, and these changes won't always be backward compatible, so we're going to version the API. This first iteration will be live at overflowing-strength-production.up.railway.app/api/v1/ and is structured as described below.

---

States

To get a list of all states in Nigeria, call the endpoint at https://overflowing-strength-production.up.railway.app/api/v1/states.

All states have the following properties:

Field	Description
name	The name of the state.
capital	The capital of the state.
latitude	The latitude of the state.
longitude	The longitude of the state.

States are identified using their names or a code, which are unique. For example, a state: https://overflowing-strength-production.up.railway.app/api/v1/state/lagos

{
  "name": "Lagos",
  "capital": "Ikeja",
  "latitude": 6.5269033,
  "longitude": 3.5774005
}

Local Government Areas (LGAs)

LGAs belong to a state and they are identified by their names. All LGAs have the following properties:

Field	Description
name	The name of the LGA.

For example, LGAs in Kaduna: https://overflowing-strength-production.up.railway.app/api/v1/state/kaduna/lgas

[
  {
    "name": "Birnin Gwari"
  },
  {
    "name": "Chikun"
  },
  {
    "name": "Giwa"
  },
  {
    "name": "Ikara"
  },
  {
    "name": "Igabi"
  },
  {
    "name": "Jaba"
  },
  {
    "name": "Jema'a"
  },
  {
    "name": "Kachia"
  },
  {
    "name": "Kaduna North"
  },
  {
    "name": "Kaduna South"
  },
  {
    "name": "Kagarko"
  },
  {
    "name": "Kajuru"
  },
  {
    "name": "Kaura"
  },
  {
    "name": "Kauru"
  },
  {
    "name": "Kubau"
  },
  {
    "name": "Kudan"
  },
  {
    "name": "Lere"
  },
  {
    "name": "Makarfi"
  },
  {
    "name": "Sabon Gari"
  },
  {
    "name": "Sanga"
  },
  {
    "name": "Soba"
  },
  {
    "name": "Zangon Kataf"
  },
  {
    "name": "Zaria"
  }
]

Cities

Cities belong to a state and they are identified by their names. All cities have the following properties:

Field	Description
name	The name of the city.

Note: City data is not currently available. The /cities endpoint returns an empty list. This data was previously stored in Parse.com, which shut down in 2017.

List of endpoints

This is just a summary of all four endpoints you can call.

• GET /states returns a list of all states in Nigeria.
• GET /state/<state_name_or_code> returns one state. You can either pass in the state name i.e lagos or the state code i.e LA.
• GET /state/<state_name_or_code>/lgas returns a list of LGAs in a state. You can either pass in the state name i.e lagos or the state code i.e LA.
• GET /state/<state_name_or_code>/cities returns a list of cities in a state. You can either pass in the state name i.e lagos or the state code i.e LA.

Contributing

We welcome any and all contributions, code cleanups and feature requests.

1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
2. Fork the repository on GitHub to start making your changes to the master branch (or branch off of it).
3. Send a pull request and bug the maintainer until it gets merged and published. :).