Developers

Public lookup API

Integrate privacy-safe address search and boundary visualisation into your applications. Public endpoints return delivery-relevant data only — no resident names or private registry records.

Public API overview

Base URL: https://ngpostal.staging.zenthra.io/api/v1

Interactive OpenAPI documentation is available at https://ngpostal.staging.zenthra.io/api/docs. That spec is the authoritative contract for request and response shapes.

API keys for high-volume business access will come later. Today, public endpoints are open for discovery and low-volume integration. Protected registry and admin APIs are not part of the public surface.

Data coverage

Address lookup — national address lookup is live. Coverage depth still varies by area as named districts and linked buildings are populated; some places may return fewer matches until data catches up.
Boundaries — state and postal area polygons are available nationally. District and postcode boundaries depend on imported hierarchy data for each area.
Streets — named street centreline data is being imported state by state from OpenStreetMap. Coverage varies; not every road name in Nigeria is present yet.

Lookup endpoints

Privacy-safe address resolution. Responses use stable derived IDs — never raw database UUIDs or resident data.

GEThttps://ngpostal.staging.zenthra.io/api/v1/lookup/address-suggest?query=kja
Universal address search — postcodes, streets, house numbers, building names, and landmark aliases.
GEThttps://ngpostal.staging.zenthra.io/api/v1/lookup/street-suggest?query=toyin
Street-name typeahead. Returns delivery-relevant address matches for a partial or full street name.
GEThttps://ngpostal.staging.zenthra.io/api/v1/lookup/postcode-suggest?query=kja2
Postcode prefix typeahead. Returns address matches as the user types a postcode.
GEThttps://ngpostal.staging.zenthra.io/api/v1/lookup/postcode/kja63bd
Resolve a full postcode to delivery-relevant address details. Accepts display or compact forms.
GEThttps://ngpostal.staging.zenthra.io/api/v1/lookup/aliases?query=banex
Search landmark and local-name aliases mapped to verified addresses.

Boundary and hierarchy endpoints

Used by the public boundary map to browse state → postal area → district and to fetch GeoJSON polygons. Raw registry geometry from protected /geo/* routes is never exposed here.

GEThttps://ngpostal.staging.zenthra.io/api/v1/boundaries/states
List Nigerian states with postal area counts.
GEThttps://ngpostal.staging.zenthra.io/api/v1/boundaries/states/LA/lgas
List postal areas in a state with centroid and bounding box summaries.
GEThttps://ngpostal.staging.zenthra.io/api/v1/boundaries/lgas/KJA
Return a GeoJSON Feature with the full postal area boundary polygon.
GEThttps://ngpostal.staging.zenthra.io/api/v1/postcodes/areas/KJA/districts
List postal districts in a postal area. Includes imported districts pending number assignment.
GEThttps://ngpostal.staging.zenthra.io/api/v1/postcodes/KJA63BD/boundary
Return a GeoJSON Feature for a postcode unit, sector, district, or area boundary.

Example response

Address suggest returns ranked, privacy-safe results with stable IDs for UI lists. Fields such as location and streetPath appear when a geolocated building or linked street centreline is available.

{
  "query": "kja",
  "count": 1,
  "results": [
    {
      "id": "ADDRESS:DP-BLD-KJA-000001-001",
      "type": "ADDRESS",
      "label": "Flat 3, 12 Toyin Street, Ikeja, IKEJA, LA, KJA6 3BD",
      "matchedText": "KJA6 3BD",
      "postcode": "KJA6 3BD",
      "buildingCode": "BLD-KJA-000001",
      "deliveryPointCode": "DP-BLD-KJA-000001-001",
      "houseNumber": "12",
      "unitLabel": "Flat 3",
      "street": {
        "officialName": "Toyin Street",
        "localityName": "Ikeja",
        "lgaCode": "IKEJA",
        "stateCode": "LA"
      },
      "building": {
        "buildingName": "Toyin Court",
        "buildingType": "RESIDENTIAL",
        "verificationStatus": "VERIFIED"
      },
      "delivery": {
        "deliverable": true,
        "verificationStatus": "VERIFIED"
      },
      "source": "REGISTRY"
    }
  ]
}

Not publicly available

Registry maintenance, building verification, alias approval, and administrative operations require authorised access. Protected /geo/* and /admin/* APIs are not documented here and are not exposed on the public internet.

Try lookup before you integrate

Use the public lookup app and boundary map to see the same data your users will receive.

Open public lookup