Address validation

Catch a wrong or incomplete address before a rider sets off: a verdict, the corrected address and postcode, and a point to deliver to.

On this page

Check an address
The answer
What to do with it

A rider loses time and money on a wrong address. Address validation checks one before you accept the order: is it real, where exactly is it, and how should it be written? It understands NIPOST postcodes, GhanaPost GPS codes and Plus Codes in the text, and fills in the postcode when it’s missing.

Check an address

cURL

curl -X POST "https://nways.ng/maps/v1/addresses/validate?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "12 Allen Avenue, Ikeja, Lagos", "country": "NG"}'

JavaScript

import { createClient } from '@nways/maps'

const nways = createClient({ key: 'YOUR_API_KEY' })
const check = await nways.validateAddress('12 Allen Avenue, Ikeja, Lagos', { country: 'NG' })
if (check.verdict.status === 'UNRESOLVED') askTheCustomerAgain()

Field	Description
`address`	Required. The address as written, up to 300 characters.
`country`	`NG`, `GH`, `BJ`, `TG`, `GA`, `CI`, `LR`, `GN`, `SL`, `GW`, `SN`, `CM`, `BF` or `CV`: where to look.
`near`	`{ lat, lng }`: where it should be (the customer’s last delivery, the shop’s area).
`lang`	`en` or `fr`.

The answer

Field	Description
`verdict.status`	`VALID` (found, to the building), `VALID_WITH_CORRECTIONS` (found, with parts corrected or added), `PARTIAL` (only to the street or area), `UNRESOLVED` (not found), `INVALID` (a code that can’t exist).
`verdict.granularity`	What it’s precise to: `PREMISE`, `POINT`, `ROUTE` (the street), `NEIGHBOURHOOD`, `LOCALITY`, `REGION` or `NONE`.
`verdict.confidence`	0 to 1.
`verdict.codesAgree`	When the text has both a code and words: whether they point to the same place.
`formattedAddress`	The address as it should be written.
`components`	Its parts (`premise`, `street`, `neighbourhood`, `locality`, `lga`, `region`, `postcode`…), each with its `source`: `input` (confirmed), `corrected`, `inferred` (added by us) or `unconfirmed`.
`location`, `accuracyM`	Where to deliver, as a GeoJSON point, and how close that is.
`postcode`	In Nigeria, the building’s NIPOST postcode with its entrances, when N-Ways knows them.
`issues`	What’s wrong or worth checking, each with a `code` and a `message`.

What to do with it

Verdict	Suggested action
`VALID`	Accept. Store `location` and the postcode with the order.
`VALID_WITH_CORRECTIONS`	Accept, and show the customer the `formattedAddress` to confirm.
`PARTIAL`	Ask for a landmark, a house number or a phone number for the rider.
`UNRESOLVED`, `INVALID`	Ask the customer to drop a pin on the map instead.