nigerian-states-lgas-and-polling-units

Complete Nigerian location data — States, LGAs, Wards and Polling Units. Sourced from INEC. Zero dependencies. Full TypeScript support out of the box.

Whether you are building a simple state/LGA dropdown, a ward selector, or a full voter registration portal — this package has you covered. Use as much or as little as you need.

Installation

npm install nigerian-states-lgas-and-polling-units

What's Inside

| Data | Count | |----------------|---------| | States | 37 | | LGAs | 774 | | Wards | 8,957 | | Polling Units | 202,297 |

I just need States

const { getStates, getState } = require('nigerian-states-lgas-and-polling-units')

// Get all 37 states
const states = getStates()
// → [{ id: "1", name: "KOGI" }, { id: "2", name: "OGUN" }, ...]

// Look up a single state by id or name (case-insensitive)
getState('5')       // → { id: "5", name: "LAGOS" }
getState('rivers')  // → { id: "11", name: "RIVERS" }
getState('999')     // → null

I need States and LGAs

const { getStates, getLGAsByState, getLGA } = require('nigerian-states-lgas-and-polling-units')

// Get all LGAs in a state
const lgas = getLGAsByState('5') // Lagos
// → [{ id: "22", name: "IKEJA", stateId: "5" }, ...]

// Look up a single LGA by id
getLGA('22')
// → { id: "22", name: "IKEJA", stateId: "5" }

Common use case — address form with state and LGA dropdowns:

const states = getStates()               // populate state dropdown
const lgas   = getLGAsByState(stateId)   // populate LGA dropdown after state is selected

I need States, LGAs and Wards

const { getLGAsByState, getWardsByLGA, getWard } = require('nigerian-states-lgas-and-polling-units')

// Get all wards in an LGA
const wards = getWardsByLGA('22')
// → [{ id: "190", name: "WARD A", lgaId: "22" }, ...]

// Look up a single ward by id
getWard('190')
// → { id: "190", name: "WARD A", lgaId: "22" }

I need Everything (including Polling Units)

const { getWardsByLGA, getPollingUnitsByWard } = require('nigerian-states-lgas-and-polling-units')

// Get all polling units in a ward
const units = getPollingUnitsByWard('190')
// → [{ id: "190-1", name: "LGEA SCHOOL IKEJA", wardId: "190" }, ...]

Common use case — full voter registration cascade:

const states       = getStates()                    // step 1
const lgas         = getLGAsByState(stateId)        // step 2
const wards        = getWardsByLGA(lgaId)           // step 3
const pollingUnits = getPollingUnitsByWard(wardId)  // step 4

One-Shot Lookup with getLocationChain

If you need multiple levels at once, use getLocationChain. Pass as many levels as you need — it returns everything in a single call.

const { getLocationChain } = require('nigerian-states-lgas-and-polling-units')

// State only → get state info + all its LGAs
getLocationChain({ stateId: '5' })
// → { state: {...}, lgas: [...] }

// State + LGA → also get wards
getLocationChain({ stateId: '5', lgaId: '22' })
// → { state: {...}, lgas: [...], lga: {...}, wards: [...] }

// State + LGA + Ward → full chain including polling units
getLocationChain({ stateId: '5', lgaId: '22', wardId: '190' })
// → { state: {...}, lgas: [...], lga: {...}, wards: [...], ward: {...}, pollingUnits: [...] }

Search

Search states, LGAs, or wards by partial name. Case-insensitive.

const { search } = require('nigerian-states-lgas-and-polling-units')

search('lag', 'state')   // → [{ id: "5", name: "LAGOS" }]
search('ikeja', 'lga')   // → [{ id: "22", name: "IKEJA", stateId: "5" }]
search('ward a', 'ward') // → [...]

The second argument is the type to search: 'state', 'lga', or 'ward'. Defaults to 'state'.

Dataset Statistics

const { getStats } = require('nigerian-states-lgas-and-polling-units')

getStats()
// → {
//     totalStates: 37,
//     totalLGAs: 774,
//     totalWards: 8957,
//     totalWardsCoveredByPollingUnits: 8957,
//     totalPollingUnits: 202297
//   }

TypeScript

No @types/ package needed. Types are bundled and work out of the box.

import {
  getStates,
  getLGAsByState,
  getWardsByLGA,
  getPollingUnitsByWard,
  getLocationChain,
  State,
  LGA,
  Ward,
  PollingUnit,
  LocationChain,
} from 'nigerian-states-lgas-and-polling-units'

const states: State[]      = getStates()
const lgas: LGA[]          = getLGAsByState('5')
const wards: Ward[]        = getWardsByLGA('22')
const units: PollingUnit[] = getPollingUnitsByWard('190')
const chain: LocationChain = getLocationChain({ stateId: '5', lgaId: '22', wardId: '190' })

Framework Examples

React — State + LGA only (simple address form)

import { useState } from 'react'
import { getStates, getLGAsByState, LGA } from 'nigerian-states-lgas-and-polling-units'

export default function AddressForm() {
  const [lgas, setLgas] = useState<LGA[]>([])

  return (
    <div>
      <select onChange={e => setLgas(getLGAsByState(e.target.value))}>
        <option value="">-- Select State --</option>
        {getStates().map(s => (
          <option key={s.id} value={s.id}>{s.name}</option>
        ))}
      </select>

      <select disabled={!lgas.length}>
        <option value="">-- Select LGA --</option>
        {lgas.map(l => (
          <option key={l.id} value={l.id}>{l.name}</option>
        ))}
      </select>
    </div>
  )
}

React — Full voter registration cascade

import { useState } from 'react'
import {
  getStates, getLGAsByState, getWardsByLGA, getPollingUnitsByWard,
  LGA, Ward, PollingUnit,
} from 'nigerian-states-lgas-and-polling-units'

export default function VoterForm() {
  const [lgas, setLgas]                 = useState<LGA[]>([])
  const [wards, setWards]               = useState<Ward[]>([])
  const [pollingUnits, setPollingUnits] = useState<PollingUnit[]>([])

  return (
    <div>
      <select onChange={e => { setLgas(getLGAsByState(e.target.value)); setWards([]); setPollingUnits([]) }}>
        <option value="">-- Select State --</option>
        {getStates().map(s => <option key={s.id} value={s.id}>{s.name}</option>)}
      </select>

      <select onChange={e => { setWards(getWardsByLGA(e.target.value)); setPollingUnits([]) }} disabled={!lgas.length}>
        <option value="">-- Select LGA --</option>
        {lgas.map(l => <option key={l.id} value={l.id}>{l.name}</option>)}
      </select>

      <select onChange={e => setPollingUnits(getPollingUnitsByWard(e.target.value))} disabled={!wards.length}>
        <option value="">-- Select Ward --</option>
        {wards.map(w => <option key={w.id} value={w.id}>{w.name}</option>)}
      </select>

      <select disabled={!pollingUnits.length}>
        <option value="">-- Select Polling Unit --</option>
        {pollingUnits.map(p => <option key={p.id} value={p.id}>{p.name}</option>)}
      </select>
    </div>
  )
}

Express.js — REST API

const express = require('express')
const {
  getStates, getLGAsByState, getWardsByLGA, getPollingUnitsByWard
} = require('nigerian-states-lgas-and-polling-units')

const app = express()

// Use only what you need
app.get('/api/states',                      (_, res) => res.json(getStates()))
app.get('/api/states/:id/lgas',      (req, res) => res.json(getLGAsByState(req.params.id)))
app.get('/api/lgas/:id/wards',       (req, res) => res.json(getWardsByLGA(req.params.id)))
app.get('/api/wards/:id/polling-units', (req, res) => res.json(getPollingUnitsByWard(req.params.id)))

app.listen(3000)

Full API Reference

| Function | Parameters | Returns | |---|---|---| | getStates() | — | State[] | | getState(identifier) | string \| number | State \| null | | getLGAsByState(stateId) | string \| number | LGA[] | | getLGA(lgaId) | string \| number | LGA \| null | | getWardsByLGA(lgaId) | string \| number | Ward[] | | getWard(wardId) | string \| number | Ward \| null | | getPollingUnitsByWard(wardId) | string \| number | PollingUnit[] | | getLocationChain(options) | { stateId, lgaId?, wardId? } | LocationChain | | search(query, type?) | string, 'state' \| 'lga' \| 'ward' | State[] \| LGA[] \| Ward[] | | getStats() | — | DataStats |

Data Source

All data is sourced from the Independent National Electoral Commission (INEC) of Nigeria and covers all 36 states plus the Federal Capital Territory (FCT).

Security

This package contains only publicly available Nigerian location data. No private or personally identifiable information is included.

To report a vulnerability, email [email protected] instead of opening a public issue.

Contributing

Contributions are welcome, especially data updates following new INEC releases.

1. Fork the repository
2. Create a branch: git checkout -b feature/your-update
3. Make changes and run tests: node tests/index.test.js
4. Commit: git commit -m "update: describe your change"
5. Push and open a pull request

Include the INEC source reference in your PR description if updating data files.

License

MIT