API_REFERENCE

Documentation

A free REST API for Nigerian address data. No signup or API key required. Every response is plain JSON.

Base URL
https://ng-address-api.vercel.app
Authentication
None required
Rate limit
20 requests / 60s
01

Response format

Every endpoint uses the same response envelope. Successful requests return a data field, with count included for list responses.

Success200
{
  "success": true,
  "count": 3,
  "data": [ ... ]
}
Error4xx
{
  "success": false,
  "error": "State with code 'XX' not found"
}
404 NOT FOUND429 RATE LIMITEDJSON ONLY
02

Data model

Location data follows a simple four-level hierarchy.

01
State
state_code
02
LGA
lga_alias
03
Ward
ward_alias
04
Town

Postal codes live on Ward records. A single code may therefore match multiple wards.

03

Endpoints

Complete API reference for states, LGAs, wards, towns, and search.

01

States

MethodEndpointDescriptionParameters
GET/api/states

Returns all Nigerian states. Supports filtering by geopolitical region.

  • regionquery

    Filter by geopolitical zone, e.g. "north central". Optional.

GET/api/states/:code

Returns a single state by its two-letter code.

  • codepathrequired

    State code, e.g. "LA".

GET/api/states/:code/lgas

Returns all LGAs belonging to a given state.

  • codepathrequired

    State code, e.g. "LA".

02

LGAs

MethodEndpointDescriptionParameters
GET/api/lgas

Returns all LGAs in the country.

—
GET/api/lgas/:alias

Returns a single LGA by its alias.

  • aliaspathrequired

    LGA alias, e.g. "ikeja".

GET/api/lgas/:alias/wards

Returns all wards belonging to a given LGA.

  • aliaspathrequired

    LGA alias, e.g. "ikeja".

03

Wards

MethodEndpointDescriptionParameters
GET/api/wards

Returns all wards. Supports reverse lookup by postal code.

  • post-codequery

    Return wards matching this postal code. A code can match more than one ward.

GET/api/wards/:alias

Returns a single ward by its alias.

  • aliaspathrequired

    Ward alias, e.g. "alausa".

GET/api/wards/:alias/towns

Returns all towns belonging to a given ward.

  • aliaspathrequired

    Ward alias, e.g. "alausa".

04

Search

MethodEndpointDescriptionParameters
GET/api/search

Case-insensitive substring search by name across states, LGAs, wards, or towns.

  • qqueryrequired

    Search term.

  • levelquery

    Scope the search. One of "all", "state", "lga", "ward", "town". Defaults to "all".