Codes

NIPOST postcodes, GhanaPost GPS addresses, Plus Codes and N-Ways home codes, in one lookup.

On this page

Any code people write as an address
Up to 100 codes of any kind at once

Note:

Send your key as key=YOUR_API_KEY on the address, or in the X-NWays-Api-Key header. API keys

Base address: https://nways.ng/maps/v1

Any code people write as an address

GET https://nways.ng/maps/v1/codes/{code}

A NIPOST postcode (LA 08 A09 DB 09, any written form), a GhanaPost GPS address (GA-183-8164), a Plus Code (6FR5J975+P4W, or a short one with near= or a town after it: J975+P4 Ikeja) or an N-Ways home code (a place's name and a number, Fréau-Jardin 10 58, in every country N-Ways issues them), URL-encoded. The kind is detected (type= forces one); the answer says the kind, where it is, a one-line address and the kind's own detail (postcode, ghanaPost, plusCode or homeCode). Text that is no kind of code answers CODE_UNRECOGNISED and isn't counted. For home codes, country= and near= pick between countries where the same name and number exist. Reasons: CODE_REQUIRED, CODE_UNRECOGNISED, TYPE_INVALID, NEAR_INVALID, COUNTRY_INVALID, LANG_INVALID, POSTCODE_INVALID, POSTCODE_NOT_FOUND_CHECK, POSTCODE_NOT_NIPOST, GHANAPOST_INVALID, GHANAPOST_UNKNOWN, PLUSCODE_INVALID, PLUSCODE_SHORT, LOCALITY_NOT_FOUND, HOMECODE_UNKNOWN, HOMECODE_FORMAT (type=homecode only), HOMECODE_OUTSIDE.

Parameters

Name	In	Type	Description
`code`	path	`string`	Required. Up to 120 characters.
`type`	query	`string`	Force a kind (default: detected). One of: `postcode`, `ghanapost`, `pluscode`, `homecode`.
`near`	query	`string`	lat,lng: rank and pick results near it.
`country`	query	`string`	Home codes: the country to look in.
`lang`	query	`string`	One of: `en`, `fr`, `pt`. Default: `en`.
`fields`	query	`string`	Comma list of the fields to keep in each result (`a.b` reaches into objects; `id` is always kept; `*` = all).

cURL

curl "https://nways.ng/maps/v1/codes/LA%2008%20A09%20DB%2009" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/codes/LA%2008%20A09%20DB%2009', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/codes/LA%2008%20A09%20DB%2009",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

The code

Field	Type	Description
`query`	`string`	Required.
`type`	`string`	Required. One of: `postcode`, `ghanapost`, `pluscode`, `homecode`.
`code`	`string`	Required. As it is written: LA 08 A09 DB 09, GA-183-8164, 6FR5J975+P4W, Fréau-Jardin 10 58.
`location`	`Point`	Required.
`location.type`	`string`	Required.
`location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`country`	`string`
`formattedAddress`	`string`
`estimated`	`boolean`
`accuracyM`	`number`
`postcode`	`Postcode`
`postcode.code`	`string`	Required.
`postcode.display`	`string`	Required.
`postcode.components`	`PostcodeComponents`	Required.
`postcode.components.state`	`string`	Required.
`postcode.components.stateName`	`string`
`postcode.components.lga`	`string`	Required.
`postcode.components.lgaName`	`string`
`postcode.components.district`	`string`	Required.
`postcode.components.area`	`string`	Required.
`postcode.components.building`	`string`	Required.
`postcode.location`	`Point`	Required.
`postcode.location.type`	`string`	Required.
`postcode.location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`postcode.name`	`string`
`postcode.address`	`string`
`postcode.buildingType`	`string`
`postcode.entrances`	`Entrance[]`	Required. Verified first, main first: route to the first.
`postcode.entrances[].location`	`Point`	Required.
`postcode.entrances[].location.type`	`string`	Required.
`postcode.entrances[].location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`postcode.entrances[].kind`	`string`	Required. One of: `main`, `gate`, `pedestrian`, `service`.
`postcode.entrances[].verified`	`boolean`	Required.
`postcode.plusCode`	`string`	Required.
`postcode.country`	`string`	Required.
`postcode.source`	`string`	Required. One of: `nipost`, `osm`, `user`, `estimate`.
`postcode.estimated`	`boolean`	Required.
`postcode.accuracyM`	`number`
`postcode.distanceM`	`number`	Reverse geocoding: from the point asked about.
`postcode.attribution`	`string`	Required.
`ghanaPost`	`Result`
`ghanaPost.id`	`string`	Required.
`ghanaPost.name`	`string`	Required.
`ghanaPost.type`	`string`	Required. address, street, business, landmark, building, postcode, ghanapost, or an area: neighbourhood, suburb, village, town, city, state…
`ghanaPost.category`	`string`
`ghanaPost.location`	`Point`	Required.
`ghanaPost.location.type`	`string`	Required.
`ghanaPost.location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`ghanaPost.bbox`	`number[]`	west, south, east, north (areas) At least 4 items, at most 4 items.
`ghanaPost.formattedAddress`	`string`
`ghanaPost.postcode`	`string`	NIPOST postcode, compact
`ghanaPost.ghanaPost`	`string`
`ghanaPost.plusCode`	`string`	Required.
`ghanaPost.country`	`string`
`ghanaPost.distanceM`	`number`	From near (or the point asked about).
`ghanaPost.estimated`	`boolean`	The point is an estimate, within accuracyM.
`ghanaPost.accuracyM`	`number`
`ghanaPost.placeId`	`string`	A business: its id for /places/{id}.
`ghanaPost.attribution`	`string`
`plusCode`	`PlusCodeResponse`
`plusCode.location`	`Point`	Required.
`plusCode.location.type`	`string`	Required.
`plusCode.location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`plusCode.plusCode`	`string`	Required.
`plusCode.country`	`Area \| null`	Required.
`plusCode.region`	`Area \| null`	Required.
`plusCode.formattedAddress`	`string`
`plusCode.postcode`	`Postcode \| null`	Required. Nigeria: the building's NIPOST postcode, when one is within reach.
`plusCode.ghanaPost`	`string \| null`	Required. Ghana: the nearest known GhanaPost GPS address (within 100 m).
`plusCode.nearest`	`Result \| null`	Required.
`plusCode.attribution`	`string`	Required.
`plusCode.bounds`	`number[]`	Required. west, south, east, north At least 4 items, at most 4 items.
`homeCode`	`HomeCode`	An N-Ways home code: a building's name-and-number address. People write `code`; `machine` carries the check digit for systems.
`homeCode.code`	`string`	Required.
`homeCode.machine`	`string`	Required. With the check digit (systems only; never shown to people).
`homeCode.country`	`string`	Required.
`homeCode.name`	`string`	Required.
`homeCode.officialName`	`string`
`homeCode.coverage`	`string`	Where an official address exists (officialAddress first). One of: `official`, `official-pending`.
`homeCode.officialAddress`	`string`
`homeCode.nameProvisional`	`boolean`	Required.
`homeCode.near`	`string`
`homeCode.municipality`	`string`	Required.
`homeCode.island`	`string`
`homeCode.postcode`	`string`
`homeCode.fullLine`	`string`	Required.
`homeCode.spoken`	`string`	Required.
`homeCode.status`	`string`	Required.
`homeCode.location`	`Point`	Required.
`homeCode.location.type`	`string`	Required.
`homeCode.location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`homeCode.entrance`	`object`
`homeCode.entrance.location`	`Point`	Required.
`homeCode.entrance.location.type`	`string`	Required.
`homeCode.entrance.location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`homeCode.entrance.kind`	`string`	Required. gate, door or centre
`homeCode.entrance.verified`	`boolean`	Required. Placed by people on site.
`homeCode.plusCode`	`string`	Required.
`homeCode.credit`	`string`	Required.
`homeCode.creditUrl`	`string (uri)`	Required.
`attribution`	`string`	Required.

200 OK

{
  "query": "string",
  "type": "postcode",
  "code": "string",
  "location": {
    "type": "string",
    "coordinates": [
      0
    ]
  },
  "country": "string",
  "formattedAddress": "string",
  "estimated": true,
  "accuracyM": 0,
  "postcode": {
    "code": "LA08A09DB09",
    "display": "LA 08 A09 DB 09",
    "components": {
      "state": "LA",
      "stateName": "Lagos",
      "lga": "08",
      "lgaName": "Eti-Osa",
      "district": "A09",
      "area": "DB",
      "building": "09"
    },
    "location": {
      "type": "string",
      "coordinates": [
        0
      ]
    },
    "name": "string",
    "address": "string",
    "buildingType": "string",
    "entrances": [
      {
        "location": {
          "type": "string",
          "coordinates": []
        },
        "kind": "main",
        "verified": true
      }
    ],
    "plusCode": "string",
    "country": "string",
    "source": "nipost",
    "estimated": true,
    "accuracyM": 0,
    "distanceM": 0,
    "attribution": "string"
  },
  "ghanaPost": {
    "id": "osm:w568367632",
    "name": "Ikeja City Mall",
    "type": "landmark",
    "category": "shopping",
    "location": {
      "type": "string",
      "coordinates": [
        0
      ]
    },
    "bbox": [
      0
    ],
    "formattedAddress": "Ikeja, Lagos",
    "postcode": "LA08A09DB09",
    "ghanaPost": "GA-183-8164",
    "plusCode": "6FR5J975+P4W",
    "country": "NG",
    "distanceM": 0,
    "estimated": true,
    "accuracyM": 0,
    "placeId": "string",
    "attribution": "string"
  },
  "plusCode": {
    "location": {
      "type": "string",
      "coordinates": [
        0
      ]
    },
    "plusCode": "string",
    "country": {
      "code": "NG-LA",
      "name": "Lagos State",
      "nameFr": "string",
      "namePt": "string"
    },
    "region": {
      "code": "NG-LA",
      "name": "Lagos State",
      "nameFr": "string",
      "namePt": "string"
    },
    "formattedAddress": "12 Admiralty Way, Lekki, Lagos State, Nigeria",
    "postcode": {
      "code": "LA08A09DB09",
      "display": "LA 08 A09 DB 09",
      "components": {
        "state": "LA",
        "stateName": "Lagos",
        "lga": "08",
        "lgaName": "Eti-Osa",
        "district": "A09",
        "area": "DB",
        "building": "09"
      },
      "location": {
        "type": "string",
        "coordinates": [
          0
        ]
      },
      "name": "string",
      "address": "string",
      "buildingType": "string",
      "entrances": [
        {
          "location": {},
          "kind": "main",
          "verified": true
        }
      ],
      "plusCode": "string",
      "country": "string",
      "source": "nipost",
      "estimated": true,
      "accuracyM": 0,
      "distanceM": 0,
      "attribution": "string"
    },
    "ghanaPost": "string",
    "nearest": {
      "id": "osm:w568367632",
      "name": "Ikeja City Mall",
      "type": "landmark",
      "category": "shopping",
      "location": {
        "type": "string",
        "coordinates": [
          0
        ]
      },
      "bbox": [
        0
      ],
      "formattedAddress": "Ikeja, Lagos",
      "postcode": "LA08A09DB09",
      "ghanaPost": "GA-183-8164",
      "plusCode": "6FR5J975+P4W",
      "country": "NG",
      "distanceM": 0,
      "estimated": true,
      "accuracyM": 0,
      "placeId": "string",
      "attribution": "string"
    },
    "attribution": "string",
    "bounds": [
      0
    ]
  },
  "homeCode": {
    "code": "Fréau-Jardin 10 58",
    "machine": "string",
    "country": "CV",
    "name": "string",
    "officialName": "string",
    "coverage": "official",
    "officialAddress": "string",
    "nameProvisional": true,
    "near": "string",
    "municipality": "string",
    "island": "string",
    "postcode": "string",
    "fullLine": "string",
    "spoken": "string",
    "status": "string",
    "location": {
      "type": "string",
      "coordinates": [
        0
      ]
    },
    "entrance": {
      "location": {
        "type": "string",
        "coordinates": [
          0
        ]
      },
      "kind": "string",
      "verified": true
    },
    "plusCode": "string",
    "credit": "Home code by N-Ways Addressing",
    "creditUrl": "string"
  },
  "attribution": "string"
}

Errors

default Error

Up to 100 codes of any kind at once

POST https://nways.ng/maps/v1/codes/batch

Each code is one unit of SKU codes. An answer per code, in order (result, as /codes/{code}), with its own error when it has one. type, near, country and lang apply to every code. Reasons (whole call): CODES_INVALID, TYPE_INVALID, NEAR_INVALID, COUNTRY_INVALID, LANG_INVALID.

Request body

Field	Type	Description
`codes`	`string[]`	Required. At least 1 items, at most 100 items.
`type`	`string`	One of: `postcode`, `ghanapost`, `pluscode`, `homecode`.
`near`	`LatLng`
`near.lat`	`number`	Required. ≥ -90, ≤ 90.
`near.lng`	`number`	Required. ≥ -180, ≤ 180.
`country`	`string`
`lang`	`string`	One of: `en`, `fr`, `pt`.

cURL

curl -X POST "https://nways.ng/maps/v1/codes/batch" \
  -H "X-NWays-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"codes":["LA08A09DB09","GA-183-8164","6FR5J975+P4W","Fréau-Jardin 10 58"]}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/codes/batch', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "codes": [
      "LA08A09DB09",
      "GA-183-8164",
      "6FR5J975+P4W",
      "Fréau-Jardin 10 58"
    ]
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/codes/batch",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"codes": ["LA08A09DB09", "GA-183-8164", "6FR5J975+P4W", "Fréau-Jardin 10 58"]},
    timeout=10,
)
data = res.json()

Response

One result per code

Field	Type	Description
`results`	`object[]`	Required.
`results[].query`	`string`	Required.
`results[].result`	`CodeResponse`
`results[].result.query`	`string`	Required.
`results[].result.type`	`string`	Required. One of: `postcode`, `ghanapost`, `pluscode`, `homecode`.
`results[].result.code`	`string`	Required. As it is written: LA 08 A09 DB 09, GA-183-8164, 6FR5J975+P4W, Fréau-Jardin 10 58.
`results[].result.location`	`Point`	Required.
`results[].result.location.type`	`string`	Required.
`results[].result.location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`results[].result.country`	`string`
`results[].result.formattedAddress`	`string`
`results[].result.estimated`	`boolean`
`results[].result.accuracyM`	`number`
`results[].result.postcode`	`Postcode`
`results[].result.postcode.code`	`string`	Required.
`results[].result.postcode.display`	`string`	Required.
`results[].result.postcode.components`	`PostcodeComponents`	Required.
`results[].result.postcode.location`	`Point`	Required.
`results[].result.postcode.name`	`string`
`results[].result.postcode.address`	`string`
`results[].result.postcode.buildingType`	`string`
`results[].result.postcode.entrances`	`Entrance[]`	Required. Verified first, main first: route to the first.
`results[].result.postcode.plusCode`	`string`	Required.
`results[].result.postcode.country`	`string`	Required.
`results[].result.postcode.source`	`string`	Required. One of: `nipost`, `osm`, `user`, `estimate`.
`results[].result.postcode.estimated`	`boolean`	Required.
`results[].result.postcode.accuracyM`	`number`
`results[].result.postcode.distanceM`	`number`	Reverse geocoding: from the point asked about.
`results[].result.postcode.attribution`	`string`	Required.
`results[].result.ghanaPost`	`Result`
`results[].result.ghanaPost.id`	`string`	Required.
`results[].result.ghanaPost.name`	`string`	Required.
`results[].result.ghanaPost.type`	`string`	Required. address, street, business, landmark, building, postcode, ghanapost, or an area: neighbourhood, suburb, village, town, city, state…
`results[].result.ghanaPost.category`	`string`
`results[].result.ghanaPost.location`	`Point`	Required.
`results[].result.ghanaPost.bbox`	`number[]`	west, south, east, north (areas) At least 4 items, at most 4 items.
`results[].result.ghanaPost.formattedAddress`	`string`
`results[].result.ghanaPost.postcode`	`string`	NIPOST postcode, compact
`results[].result.ghanaPost.ghanaPost`	`string`
`results[].result.ghanaPost.plusCode`	`string`	Required.
`results[].result.ghanaPost.country`	`string`
`results[].result.ghanaPost.distanceM`	`number`	From near (or the point asked about).
`results[].result.ghanaPost.estimated`	`boolean`	The point is an estimate, within accuracyM.
`results[].result.ghanaPost.accuracyM`	`number`
`results[].result.ghanaPost.placeId`	`string`	A business: its id for /places/{id}.
`results[].result.ghanaPost.attribution`	`string`
`results[].result.plusCode`	`PlusCodeResponse`
`results[].result.plusCode.location`	`Point`	Required.
`results[].result.plusCode.plusCode`	`string`	Required.
`results[].result.plusCode.country`	`Area \| null`	Required.
`results[].result.plusCode.region`	`Area \| null`	Required.
`results[].result.plusCode.formattedAddress`	`string`
`results[].result.plusCode.postcode`	`Postcode \| null`	Required. Nigeria: the building's NIPOST postcode, when one is within reach.
`results[].result.plusCode.ghanaPost`	`string \| null`	Required. Ghana: the nearest known GhanaPost GPS address (within 100 m).
`results[].result.plusCode.nearest`	`Result \| null`	Required.
`results[].result.plusCode.attribution`	`string`	Required.
`results[].result.plusCode.bounds`	`number[]`	Required. west, south, east, north At least 4 items, at most 4 items.
`results[].result.homeCode`	`HomeCode`	An N-Ways home code: a building's name-and-number address. People write `code`; `machine` carries the check digit for systems.
`results[].result.homeCode.code`	`string`	Required.
`results[].result.homeCode.machine`	`string`	Required. With the check digit (systems only; never shown to people).
`results[].result.homeCode.country`	`string`	Required.
`results[].result.homeCode.name`	`string`	Required.
`results[].result.homeCode.officialName`	`string`
`results[].result.homeCode.coverage`	`string`	Where an official address exists (officialAddress first). One of: `official`, `official-pending`.
`results[].result.homeCode.officialAddress`	`string`
`results[].result.homeCode.nameProvisional`	`boolean`	Required.
`results[].result.homeCode.near`	`string`
`results[].result.homeCode.municipality`	`string`	Required.
`results[].result.homeCode.island`	`string`
`results[].result.homeCode.postcode`	`string`
`results[].result.homeCode.fullLine`	`string`	Required.
`results[].result.homeCode.spoken`	`string`	Required.
`results[].result.homeCode.status`	`string`	Required.
`results[].result.homeCode.location`	`Point`	Required.
`results[].result.homeCode.entrance`	`object`
`results[].result.homeCode.plusCode`	`string`	Required.
`results[].result.homeCode.credit`	`string`	Required.
`results[].result.homeCode.creditUrl`	`string (uri)`	Required.
`results[].result.attribution`	`string`	Required.
`results[].error`	`ItemError`
`results[].error.code`	`integer`	Required.
`results[].error.reason`	`string`	Required.
`results[].error.message`	`string`	Required.
`attribution`	`string`	Required.

200 OK

{
  "results": [
    {
      "query": "string",
      "result": {
        "query": "string",
        "type": "postcode",
        "code": "string",
        "location": {
          "type": "string",
          "coordinates": []
        },
        "country": "string",
        "formattedAddress": "string",
        "estimated": true,
        "accuracyM": 0,
        "postcode": {
          "code": "LA08A09DB09",
          "display": "LA 08 A09 DB 09",
          "components": {},
          "location": {},
          "name": "string",
          "address": "string",
          "buildingType": "string",
          "entrances": [],
          "plusCode": "string",
          "country": "string",
          "source": "nipost",
          "estimated": true,
          "accuracyM": 0,
          "distanceM": 0,
          "attribution": "string"
        },
        "ghanaPost": {
          "id": "osm:w568367632",
          "name": "Ikeja City Mall",
          "type": "landmark",
          "category": "shopping",
          "location": {},
          "bbox": [],
          "formattedAddress": "Ikeja, Lagos",
          "postcode": "LA08A09DB09",
          "ghanaPost": "GA-183-8164",
          "plusCode": "6FR5J975+P4W",
          "country": "NG",
          "distanceM": 0,
          "estimated": true,
          "accuracyM": 0,
          "placeId": "string",
          "attribution": "string"
        },
        "plusCode": {
          "location": {},
          "plusCode": "string",
          "country": {},
          "region": {},
          "formattedAddress": "12 Admiralty Way, Lekki, Lagos State, Nigeria",
          "postcode": {},
          "ghanaPost": "string",
          "nearest": {},
          "attribution": "string",
          "bounds": []
        },
        "homeCode": {
          "code": "Fréau-Jardin 10 58",
          "machine": "string",
          "country": "CV",
          "name": "string",
          "officialName": "string",
          "coverage": "official",
          "officialAddress": "string",
          "nameProvisional": true,
          "near": "string",
          "municipality": "string",
          "island": "string",
          "postcode": "string",
          "fullLine": "string",
          "spoken": "string",
          "status": "string",
          "location": {},
          "entrance": {},
          "plusCode": "string",
          "credit": "Home code by N-Ways Addressing",
          "creditUrl": "string"
        },
        "attribution": "string"
      },
      "error": {
        "code": 0,
        "reason": "string",
        "message": "string"
      }
    }
  ],
  "attribution": "string"
}

Errors

default Error