Lookup levels

Lookup responses are graded into 5 cumulative levels: each higher level adds attributes on top of the ones below it. Request a level with the level query param; the response is capped at your organization’s granted level.

Attribute	L1	L2	L3	L4	L5
Validity status	✓	✓	✓	✓	✓
Administrative address		✓	✓	✓	✓
Recent house address		✓	✓	✓	✓
Building use status			✓	✓	✓
Other building info				✓	✓
Point geometry (coordinates)					✓

Every lookup needs an API key. L1 is free (no credits). L2–L3 are commercial (consume credits).

Example

# L1: validity only
curl "https://api.postcode.gov.ng/v1/lookup?code=EK-01-A03-FK-01&level=1" \
  -H "X-API-Key: nipost_live_xxx"

# L3: everything (requires granted L3 key)
curl "https://api.postcode.gov.ng/v1/lookup?code=EK-01-A03-FK-01&level=3" \
  -H "X-API-Key: nipost_live_xxx"

L3 response

{
  "data": {
    "postcode": "EK-01-A03-FK-01",
    "valid": true,
    "administrative_address": { "state_name": "EKITI", "lga_name": "ADO EKITI", "locality_name": "ADO EKITI", "zone": "SOUTH WEST" },
    "recent_house_address": { "recent": "NTA ROAD, BACK OF FABIAN HOTEL, ADO EKITI" },
    "building_use_status": "residential"
  }
}

Sample postcodes

These are live postcodes for use with a live key (nipost_live_…). They do not resolve under a test key — a test key reads a separate sandbox dataset. For codes that work with a test key, see the sandbox postcodes (or call search/autocomplete with your test key to discover more).

Real, active postcodes for exercising a live integration across a spread of states:

Postcode	State
`AK-11-I61-ZF-12`	Akwa Ibom
`AK-11-H40-WD-11`	Akwa Ibom
`BA-02-M67-BL-69`	Bauchi
`BA-02-E99-NE-30`	Bauchi
`EB-13-G95-FR-90`	Ebonyi
`EB-13-I97-AB-30`	Ebonyi
`EN-05-V19-CD-22`	Enugu
`EN-05-V19-FT-20`	Enugu
`FC-03-B06-AG-12`	FCT
`FC-02-B19-RT-30`	FCT
`JI-24-O18-JP-23`	Jigawa
`JI-24-N11-VM-58`	Jigawa
`KN-31-F82-WJ-80`	Kano
`KN-31-D78-IQ-38`	Kano
`LA-11-W06-TC-10`	Lagos
`LA-11-U34-ZR-63`	Lagos
`NI-09-J67-QC-65`	Niger
`NI-09-A75-DA-10`	Niger
`OG-14-T18-BN-16`	Ogun
`OG-14-M82-QA-09`	Ogun

Need a higher level? Request it under Settings → KYB & Access in the dashboard.

Getting started

Concepts

Widget

Example

Sample postcodes

​Example

​Sample postcodes

Example

Sample postcodes