Nigeria States → LGAs → Towns (Data package)

Dataset and helpers for Nigerian states, their capitals, Local Government Areas (LGAs), and towns/cities. Built for developers who need a dependable, copy‑paste‑ready source of Nigerian administrative data.

Quick links

• Install: Installation
• Use it: Usage
• Data shape: Data reference
• Contribute: Contributing
• Dev setup: Local development

Features

• Comprehensive list of states, capitals, LGAs, and towns
• Stable JS helpers for common lookups
• Lightweight package, easy to integrate

Installation

npm install nigeria-state-lga-data
# or
yarn add nigeria-state-lga-data

Node: works on current LTS releases. The library is published as CommonJS. You can use it in any JavaScript project (Node.js directly, or via bundlers like Vite/Webpack). For browser usage, bundle it with your app.

Usage

CommonJS (Node.js)

const {
  getStates,
  getStatesAndCapitals,
  getLgas,
  getTowns,
  getCapital,
  getState,
  getStatesData,
} = require('nigeria-state-lga-data');

console.log(getStates());
console.log(getStatesAndCapitals());
console.log(getLgas('Lagos'));
console.log(getTowns('Lagos'));
console.log(getCapital('Kano'));
console.log(getState('Rivers'));
console.log(getStatesData());

ES Modules

import pkg from 'nigeria-state-lga-data';
const {
  getStates,
  getStatesAndCapitals,
  getLgas,
  getTowns,
  getCapital,
  getState,
  getStatesData,
} = pkg; // CJS default export → destructure helpers

console.log(getStates());

Data reference

The primary dataset lives in data/nigeria.json and follows this structure:

{
  "states": [
    {
      "name": "Abia",
      "capital": "Umuahia",
      "lgas": ["Aba North", "Aba South", "Arochukwu", "Bende", "..."] ,
      "towns": ["Aba", "Umuahia", "Ohafia", "..."]
    }
  ]
}

Minimal example of a single state object:

{
  "name": "Lagos",
  "capital": "Ikeja",
  "lgas": ["Agege", "Alimosho", "Eti-Osa", "Ikeja", "Ikorodu", "..."],
  "towns": ["Ikeja", "Lekki", "Ikorodu", "Epe", "Badagry", "..."]
}

Notes:

• Towns are currently listed at the state level (not per LGA).

API (helpers)

From index.js:

| Helper | Params | Returns | Description | Notes | | :-- | :-- | :-- | :-- | :-- | | getStates | () | string[] | List of all state names. | Order matches dataset. | | getStatesAndCapitals | () | { state: string; capital: string }[] | Pairs of state and capital. | Useful for dropdowns. | | getLgas | (state: string) | string[] | LGAs for a given state. | Case-insensitive; returns [] if not found. | | getTowns | (state: string) | string[] | Towns/cities for a given state. | Case-insensitive; returns [] if not found. | | getCapital | (state: string) | string | Capital name for a given state. | Returns '' if not found. | | getState | (state: string) | { name: string; capital: string; lgas: string[]; towns: string[] } \| null | Full state record. | Returns null if not found. | | getStatesData | () | { name: string; capital: string; lgas: string[]; towns: string[] }[] | Full dataset shallow-copied per state. | Safe to read and map. |

Contributing

Want to contribute data or improvements? See CONTRIBUTION.md for the full guide, dev setup, and PR checklist.

Release and versioning

We follow SemVer. Non-breaking data additions are minor bumps; breaking shape changes are major bumps. Changelog entries go in PR descriptions and release notes.

Issues

Found a problem or need help? Open an issue on GitHub.

License

MIT — see LICENSE.

If this project helps you, please ⭐️ the repo and share it.