Our API exposes resources through various HTTP endpoints using GET requests. All API endpoints are located at:

https://api.facts.ng/v1/*

Authentication

Authentication is not required to use our API.

Errors

Success is indicated via standard HTTP status codes. A 200 status code indicates success and a 400 status code indicates an error on your side. Any 5xx codes indicate an error on our side.

Reference

GET /states

Returns a summary of all the states.

Basic Usage:

curl https://api.facts.ng/v1/states

Example JSON Response Body:

[
  {
    "id": "abia",
    "name": "Abia",
    "uri": "https://api.facts.ng/v1/states/abia",
    "region": "South East",
    "capital": "Umuahia",
    "deputy": "Ude Oko Chukwu",
    "governor": "Okezie Ikpeazu",
    "slogan": "God's Own State"
  },
  {
    "id": "adamawa",
    "name": "Adamawa",
    "uri": "https://api.facts.ng/v1/states/adamawa",
    "region": "North East",
    "capital": "Yola",
    "deputy": "Martins Babale",
    "governor": "Bindo Jibrilla",
    "slogan": "Highest Peak Of The Nation"
  },
  ...
]

GET /states/$id

Returns details for a specific state.

Basic Usage:

curl https://api.facts.ng/v1/states/lagos

Example JSON Response Body:

  "id": "lagos",
  "name": "Lagos",
  "uri": "https://api.facts.ng/v1/states/lagos",
  "region": "South West",
  "capital": "Ikeja",
  "deputy": "Oluranti Adebule",
  "governor": "Akinwumi Ambode",
  "lgas": [
    "Agege",
    "Ajeromi-Ifelodun",
    "Alimosho",
    "Amuwo-Odofin",
    "Apapa",
    "Badagary",
    "Epe",
    "Eti-Osa",
    "Ibeju-Lekki",
    "Ifako-Ijaye",
    "Ikeja",
    "Ikorodu",
    "Kosofe",
    "Lagos Island",
    "Lagos Mainland",
    "Mushin",
    "Ojo",
    "Oshodi-Isolo",
    "Somolu",
    "Surulere"
  ],
  "neighbours": [
    "Ogun"
  ],
  "slogan": "Centre Of Excellence",
  "towns": [
    "Agege",
    "Badagry",
    "Epe",
    "Ikorodu",
    "Ikoyi",
    "Mushin",
    "Surulere",
    "Victoria Island"
  ]
}

GET /states/random

Returns details for a random selection of states.
By default returns 4 random states (use case optimised for our use on www.quiz.ng).

Basic Usage:

curl https://api.facts.ng/v1/states/random

Usage with desired limit:

curl https://api.facts.ng/v1/states/random?limit=2