ng-address-resolver
Resolve free-text Nigerian addresses, such as "back of Fabian Hotel, off NTA Road, Ado Ekiti", to NIPOST digital postcodes (NDAPS). It answers only as precisely as the evidence allows, and asks a question when it cannot.
Status: pre-release. The workflow is tested against mocked Claude, NIPOST and geocoder APIs. It has not yet been run end to end with live NIPOST and Claude credentials, and its accuracy on real addresses is unmeasured.
How it decides
- A postcode written in the text is extracted (never auto-corrected) and confirmed with NIPOST.
- A location pin is reverse-geocoded by NIPOST. This is the only route to a high-confidence building code.
- Text only is read by Claude into street, landmarks and their relation ("behind", "opposite", "at"), area, LGA and state, then placed with a geocoder and reverse-geocoded by NIPOST.
| Evidence | Answer |
|---|---|
| Typed postcode NIPOST confirms, or a pin within 10 m of a building | Building code, high confidence |
| A pin within 25 m, or the landmark the address is | Building code, medium confidence |
| A building near a landmark ("behind", "opposite") | Area code, e.g. EK-01-A03-FK |
| A street only | District code, low confidence |
| A town only, or nothing found | No code, plus a question for the user |
Text alone rarely identifies a building: a landmark's own building is not the one behind it, and a road's map point is not any house on it. Ask users for a location pin when you need the exact building.
Usage
ng-address "back of Fabian Hotel, off NTA Road, Ado Ekiti"
ng-address "my house" --lat 7.6211 --lng 5.2214
The result is JSON: status (resolved, partial, unresolved), code, level, confidence, method, question and the evidence behind it.
from ng_address import Resolver
result = await Resolver(nipost=..., parser=..., geocoder=...).resolve("...")
The core needs no model. Install ng-address-resolver[claude] to let the CLI and ng_address.parse.ClaudeParser read addresses with Claude. A caller that has already read the address, such as the host model of an MCP server, passes its own ParsedAddress as resolve(..., parsed=...) instead.
Configuration
| Variable | Purpose |
|---|---|
| Anthropic credentials | Needs the claude extra. Read by the Anthropic SDK (ANTHROPIC_API_KEY or an ant auth login profile). Without them the raw text is searched instead. |
NG_POSTCODE_API_KEY |
NIPOST API key. Without it no postcode can be returned. |
NG_GEOCODER_URL |
A Nominatim server, ideally your own. |
NG_GEOCODER_CONTACT |
A URL or email sent in the User-Agent to identify you. Required for the public Nominatim. |
NG_ADDRESS_MODEL |
Claude model. Defaults to claude-opus-5-5. |
The public Nominatim at https://nominatim.openstreetmap.org allows light personal use only. A service whose main job is geocoding must run its own instance or use a commercial geocoder. Map data © OpenStreetMap contributors.
Each address uses at most one Claude call at low effort, up to three geocoder searches, and one or two NIPOST calls.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for ng-address-resolver 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ng_address_resolver-0.1.0.tar.gz | 15.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ng_address_resolver-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 30.3 kB
Release files / ng_address_resolver-0.1.0.tar.gz
| Download URL | ng_address_resolver-0.1.0.tar.gz |
|---|---|
| Size | 15.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
864e125cc336a8edb171ad6b6b36ec7617ccf5d74dee429a71352088b07c5c51
|
|
BLAKE2b-256 checksum How to use checksums |
34a05a47cee45287d6b94b6e78110216a99c9dac9ff4f31629460ba3db9eae8a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / ng_address_resolver-0.1.0-py3-none-any.whl
| Download URL | ng_address_resolver-0.1.0-py3-none-any.whl |
|---|---|
| Size | 14.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
58a616bc71c791bcad565acef2e011a05997214de68e5cd1735818d6a98f33bb
|
|
BLAKE2b-256 checksum How to use checksums |
81bb541497c1e839b0ff18f9ead0eebd1b1c374c013089ff684a828d4abfadab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency log
