A small JSON object for passing a Nigerian address between systems. It is built around the building postcode NIPOST issues, and it maps onto the address formats that payments, health, web, and postal systems already use.
{
"postcode": { "code": "EK-01-A03-FK-01", "level": "building", "assigned": true, "checked_at": "2026-10-03T12:00:00Z" },
"country": "NG",
"state": "Ekiti",
"lga": "Ado Ekiti",
"locality": "Ado Ekiti",
"street_address": "12 NTA Road",
"location": { "lat": 7.6211, "lng": 5.2214 }
}
Validate a record against the JSON Schema. Only postcode and country are required, and a receiver ignores fields it does not know.
| Field | Holds | Where it comes from |
|---|---|---|
postcode |
A postcode reference: the code, its level, and optionally a confidence and whether NIPOST confirmed it | A code the person gave, a location pin, or resolve_address |
country |
NG |
Fixed |
state |
State name | state_name in NIPOST’s lookup |
lga |
Local government area name | lga_name in NIPOST’s lookup |
locality |
Town or locality name | locality_name in NIPOST’s lookup |
street_address |
House number and street on one line | The person, or recent_house_address in NIPOST’s lookup |
description |
What else locates the place, such as “behind Fabian Hotel” | The person |
location |
A point on the building, in WGS 84 decimal degrees | A location pin |
NIPOST returns the three names and the house address from lookup level 2, which needs a key granted that level. These libraries hold no tables of names, so leave a name out when you have not looked it up.
level is more useful to the receiver than a building code that was guessed.EK-01-A03-FK-01 in a record or a message, and the compact EK01A03FK01 in a database column.| Record | ISO 20022 PstlAdr |
FHIR Address |
schema.org PostalAddress |
vCard ADR |
|---|---|---|---|---|
postcode.code |
PstCd |
postalCode |
postalCode |
postal code |
country |
Ctry |
country |
addressCountry |
country name |
state |
CtrySubDvsn |
state |
addressRegion |
region |
lga |
DstrctNm |
district |
none | none |
locality |
TwnNm |
city |
addressLocality |
locality |
street_address |
StrtNm and BldgNb, or an AdrLine in a hybrid address |
line |
streetAddress |
street address |
description |
An AdrLine in a hybrid address |
line |
none | none |
location |
none | The geolocation extension |
geo on the enclosing Place |
The separate GEO property |
PstCd holds up to 16 characters, so the 15-character hyphenated code fits as written. TwnNm, DstrctNm, and CtrySubDvsn hold up to 35 characters each, StrtNm and an AdrLine up to 70, and BldgNb up to 16.
Swift is retiring unstructured addresses from cross-border payments in favour of structured and hybrid ones. In a hybrid address the town and the country are mandatory in their own fields, with up to two free-text lines beside them, according to bank guidance. locality and country cover that minimum. The date, the field lengths, and the mandatory fields depend on the message version and the market, so check Swift’s current notices and the usage guideline you send under.
The Universal Postal Union (UPU) publishes an addressing sheet for Nigeria, dated October 2022, that sets out the lines of a Nigerian address. The record’s fields fall onto those lines in this order.
| Line | UPU’s label | From the record |
|---|---|---|
| 1 | addressee | The person or organisation, which the record leaves to you |
| 2 | house no + street | street_address |
| 3 | locality + postcode | locality, then postcode.code |
| 4 | sub-province | lga |
| 5 | province | state, in capitals |
| 6 | country | NIGERIA, in capitals, on an item sent from abroad |
Mrs Ada Obi
12 NTA Road
Ado Ekiti EK-01-A03-FK-01
Ado Ekiti
EKITI STATE
NIGERIA
The sheet predates the digital postcode and shows a six-digit code to the right of the locality. NIPOST has published no layout for the new code that this project could find, so the example carries the 2022 position forward. Follow NIPOST’s guidance once it appears. The sheet has no line for description or location.
UPU’s standard for address data is S42, International postal address components and templates. It names the elements of an address and gives each country a template for arranging them. UPU’s public overview of S42 shows the elements below. This project found no S42 template for Nigeria on UPU’s site.
| Record | S42 element in UPU’s overview |
|---|---|
street_address |
Street No, Street Name, Street type |
locality |
Town |
state |
Region |
postcode.code |
Postcode |
country |
Country |
lga |
none shown |
The full list of S42 elements and their codes is in UPU’s Technical Standards Manual, which is sold and which this project has not read. The table above goes only as far as UPU’s public overview does.
ISO 19160-4:2023, Addressing, Part 4: International postal address components and template language, is the ISO standard for the same subject. Its text is sold, so the points below come from its published abstract alone.
postcode.code is an element in these terms.state and lga are two levels of administrative region in Nigeria, so they fit that mechanism.The element codes are in the body of the standard, so this page gives no code-by-code mapping.