Skip to content

Latest commit

 

History

History
110 lines (84 loc) · 7.07 KB

address-record.md

File metadata and controls

110 lines (84 loc) · 7.07 KB
description A JSON record for Nigerian addresses built on the NIPOST building postcode, mapped to ISO 20022, FHIR, schema.org, vCard and UPU's layout.

A Nigerian address record

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.

Fields

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.

Rules

  • Send the code at the level you know: an area or district code with its level is more useful to the receiver than a building code that was guessed.
  • Write the hyphenated form: EK-01-A03-FK-01 in a record or a message, and the compact EK01A03FK01 in a database column.
  • Fill another format's postcode field only at building level: a coarser code is a prefix of a postcode. Keep it in the record and leave the other format's field empty.
  • Treat it as personal data: an address tied to a person is covered by the Nigeria Data Protection Act.

Mapping to other formats

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

Payments

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.

Post

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

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.

  • Three levels of component: elements, such as an organization name or a postcode; constructs, which group elements; and segments, which group constructs by function. postcode.code is an element in these terms.
  • Sub-elements for levels of administrative region: the standard lets one element occur at several levels. state and lga are two levels of administrative region in Nigeria, so they fit that mechanism.
  • No fixed lengths or value ranges: the standard sets neither for any component, so nothing in it restricts a postcode to six digits.
  • Templates: each country's rendering rules are written as a template that software can process. A template for Nigeria would carry the line order shown under Post above.

The element codes are in the body of the standard, so this page gives no code-by-code mapping.