Glossary
Unofficial, open-source developer tools for Nigeria’s National Digital Postcode. This glossary fixes one name for each concept, in every language and every repo.
Language
Section titled “Language”The postcode
Section titled “The postcode”Postcode: The 11-character code that NIPOST gives to one addressable building or location. Avoid: digital address, address code, zip code, postal code
Legacy postcode: An old 6-digit NIPOST postcode. It names an area, not a building. Avoid: old code, zip
Segment: One of the five parts of a postcode: state, LGA, district, area and unit. Avoid: part, field, component, chunk
State: The first segment. Two letters that name one of the 36 states or the Federal Capital Territory. Avoid: region, province
LGA: The second segment. Two digits that name a local government area within a state. Avoid: council, local government, municipality
District: The third segment. Three characters that name a district within an LGA. Avoid: sorting code, sector
Area: The fourth segment. Two letters that name the smallest polygon in the system. An area holds at most 99 units. Avoid: zone, block, neighbourhood
Unit: The fifth segment. Two digits that name one building or delivery point within an area. Avoid: building number, house number, delivery unit
Partial postcode:
A postcode that stops after the state, LGA, district or area segment.
Avoid: prefix, incomplete code
Exception: prefix is the name of the first parameter of contains.
Precision: The most specific segment that a postcode or a result contains. Avoid: level, granularity, resolution
Forms of a postcode
Section titled “Forms of a postcode”Compact form:
The postcode with no separators, for example EK01A03FK01.
Avoid: raw, plain
Canonical form:
The postcode with hyphens between segments, for example EK-01-A03-FK-01.
Avoid: formatted, standard form
Display form:
The postcode with spaces between segments, for example EK 01 A03 FK 01.
Avoid: pretty, human form
Normalise:
To change input in three steps, in this order: apply NFKC, remove the separators, and change the ASCII letters to upper case. grammar.md defines the steps.
Avoid: sanitise, canonicalise
Code point: One Unicode code point. It is not a UTF-16 unit, a byte or a grapheme cluster. For example, U+1D404 is one code point and two UTF-16 units. Avoid: character (when you count input), char
Input limit:
The most code points that parse and isLegacy read. It is maxInputCodePoints in data/format.json. Over the limit, parse gives bad_length and isLegacy gives false. Both functions apply the limit before they normalise.
Avoid: max length, length limit, size limit
Suggestion:
The canonical form that parse offers with unknown_state or bad_segment, when a fix of look-alike characters makes the code parse. It is a hint, never a success. The word means this hint from parse. It does not mean the suggestions that NIPOST’s autocomplete API returns.
Avoid: correction, autocorrect
Parse result:
What parse returns: a postcode, or a parse error. The Interface section of grammar.md defines its fields.
Avoid: outcome, response
Parse error:
The reason that parse rejected its input. It has a code, the failing segment and a suggestion. It is a value that parse returns, not an exception.
Avoid: validation error, exception
NIPOST’s API
Section titled “NIPOST’s API”Gateway:
NIPOST’s public API at api.postcode.gov.ng.
Avoid: server, backend, endpoint (for the whole API)
Lookup: A request to the gateway for the facts about one postcode. Avoid: query, fetch, resolve
Lookup level: How much data a lookup returns, from 1 for validity only to 5 for point geometry. Avoid: tier, access level, depth
Reverse geocode: A request for the nearest unit to a coordinate. Avoid: reverse lookup, locate
Accuracy: The radius in metres within which a GPS fix is likely correct. Avoid: precision, error margin
Secret key:
An API key for servers. It starts with nipost_test_ or nipost_live_.
Avoid: private key, API secret
Publishable key:
An API key that can ship inside an app or a web page. It starts with nipost_pk_.
Avoid: public key, client key
Widget: NIPOST’s own postcode picker. Gatepost does not build widgets. Avoid: using this word for a Gatepost component
Gatepost
Section titled “Gatepost”Spec:
The spec repo. It holds the grammar, the client contract, the data, the vectors, the fixtures, the completed OpenAPI file and the standards.
Avoid: schema, contract (for the repo)
Contract scenario:
One shared test case in spec/contract/. It names the calls, the mock server’s responses and the outcome that every client must reach.
Avoid: contract test (for the file), vector, fixture
Attempt: One request that a client sends for one call. A retry is the second or third attempt. Avoid: try, request (when you count them)
Evidence:
How Gatepost knows the shape of a gateway response: observed in its own calls, documented by NIPOST only, or assumed by the mock server.
Avoid: source, confidence, proof
Vector:
One shared test case in spec/vectors/ that every SDK must pass.
Avoid: fixture, example, golden file
Fixture: Synthetic data that the mock server returns. Avoid: vector, stub, sample
Mock server: The local server that imitates the gateway with fixtures. Avoid: fake API, stub server, sandbox
SDK: The core and the client for one language. Avoid: library (for the pair), wrapper, binding
Core: The part of an SDK that parses and formats postcodes without network access. Avoid: utils, base, common
Client: The part of an SDK that calls the gateway. Avoid: API wrapper, service, fetcher
Field: A Gatepost UI component in which a user enters or picks a postcode. Avoid: input, widget, picker
Confirm: To show the user what a postcode points to before the app stores it. Avoid: verify, validate (for this step)
Check status:
What the WooCommerce plugin learned about the postcode of an order: valid, invalid, unchecked or error. The order meta _gatepost_postcode_check holds it.
Avoid: verification status, validation result
Form value: The text that a field gives its form when the form is sent: the canonical form of a postcode, the 6 digits of a legacy postcode, or the text without white space at the start and the end. Avoid: submitted value, output
Message catalogue: A data file that holds the text of a UI in one language, one message for each key. Avoid: strings file, translations, locale file
Tell: A habit that makes code look machine-written, such as very long lines. Avoid: smell (smells are design problems), anti-pattern
Unofficial. Not made or endorsed by NIPOST.