Quickstart - Postcode

1. Get an API key

Create an account in the developer dashboard, then go to Settings → API Keys → Create key. Copy the secret; it’s only shown once.

Every endpoint needs an API key. Search and Lookup L1 are free (they consume no credits); Lookup L2+ spends credits.

2. Make a request

Pass your key in the X-API-Key header.

curl "https://api.postcode.gov.ng/v1/lookup?code=EK-01-A03-FK-01&level=1"

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

const res = await fetch(
  "https://api.postcode.gov.ng/v1/lookup?code=EK-01-A03-FK-01&level=3",
  { headers: { "X-API-Key": "nipost_live_xxx" } }
);
const { data } = await res.json();
console.log(data);

3. 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"
  }
}

The attributes returned depend on the level you request and your granted access level. See Lookup levels.

Try autocomplete

Type-ahead suggestions are free (no credits), but still need a key:

curl "https://api.postcode.gov.ng/v1/search/autocomplete?q=EK01" \
  -H "X-API-Key: $POSTCODE_API_KEY"