Geocoding

Search for places and addresses, what's at a point, and NIPOST, GhanaPost and Plus Code lookups.

On this page

Search for places, addresses and codes
What's at a point
A NIPOST postcode
Up to 100 NIPOST postcodes at once
A GhanaPost GPS address
A Plus Code's area and what's there

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

Search for places, addresses and codes

GET https://nways.ng/maps/v1/geocode

Places, streets, addresses, landmarks, businesses and areas in every covered country, with typos and local nicknames; a NIPOST postcode finds its building, a GhanaPost GPS address its point. Nearer results first when near is given. Reasons: QUERY_REQUIRED, QUERY_TOO_LONG, NEAR_INVALID, COUNTRY_INVALID, LIMIT_INVALID, LANG_INVALID.

Parameters

Name	In	Type	Description
`q`	query	`string`	Required. Up to 200 characters.
`near`	query	`string`	lat,lng: rank and pick results near it.
`country`	query	`string`	Comma list of NG, GH, BJ, TG, GA, CI, LR, GN, SL, GW, SN, CM, BF, CV, GM.
`limit`	query	`integer`	Default: `8`. ≥ 1, ≤ 20.
`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/geocode?q=Ikeja+City+Mall" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/geocode?q=Ikeja+City+Mall', {
  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/geocode?q=Ikeja+City+Mall",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

Results

Field	Type	Description
`results`	`Result[]`	Required.
`results[].id`	`string`	Required.
`results[].name`	`string`	Required.
`results[].type`	`string`	Required. address, street, business, landmark, building, postcode, ghanapost, or an area: neighbourhood, suburb, village, town, city, state…
`results[].category`	`string`
`results[].location`	`Point`	Required.
`results[].location.type`	`string`	Required.
`results[].location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`results[].bbox`	`number[]`	west, south, east, north (areas) At least 4 items, at most 4 items.
`results[].formattedAddress`	`string`
`results[].postcode`	`string`	NIPOST postcode, compact
`results[].ghanaPost`	`string`
`results[].plusCode`	`string`	Required.
`results[].country`	`string`
`results[].distanceM`	`number`	From near (or the point asked about).
`results[].estimated`	`boolean`	The point is an estimate, within accuracyM.
`results[].accuracyM`	`number`
`results[].placeId`	`string`	A business: its id for /places/{id}.
`results[].attribution`	`string`
`didYouMean`	`string`
`attribution`	`string`	Required.

200 OK

{
  "results": [
    {
      "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"
    }
  ],
  "didYouMean": "string",
  "attribution": "string"
}

Errors

default Error

What's at a point

GET https://nways.ng/maps/v1/reverse

One shape in every covered country: the country and region, the Plus Code, Nigeria's NIPOST postcode (the building within reach), Ghana's nearest known GhanaPost GPS address, and the nearest named address, street or landmark (else the area), with a one-line address. Reasons: LAT_LNG_REQUIRED, RADIUS_INVALID, LANG_INVALID.

Parameters

Name	In	Type	Description
`lat`	query	`number`	Required.
`lng`	query	`number`	Required.
`radius`	query	`number`	How far to look for an address, street or landmark (metres). Default: `200`. ≥ 10, ≤ 1000.
`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/reverse?lat=6.4474&lng=3.472" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/reverse?lat=6.4474&lng=3.472', {
  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/reverse?lat=6.4474&lng=3.472",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

What's there

Field	Type	Description
`location`	`Point`	Required.
`location.type`	`string`	Required.
`location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`plusCode`	`string`	Required.
`country`	`Area \| null`	Required.
`region`	`Area \| null`	Required.
`formattedAddress`	`string`
`postcode`	`Postcode \| null`	Required. Nigeria: the building's NIPOST postcode, when one is within reach.
`ghanaPost`	`string \| null`	Required. Ghana: the nearest known GhanaPost GPS address (within 100 m).
`nearest`	`Result \| null`	Required.
`attribution`	`string`	Required.

200 OK

{
  "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": {
          "type": "string",
          "coordinates": []
        },
        "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"
}

Errors

default Error

A NIPOST postcode

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

The building a NIPOST postcode names (any written form: LA 08 A09 DB 09, la-08-a09-db-09), its entrances (route to the first), its parts and their names; or, for a code we haven't placed yet, where it is estimated to be from the codes around it (estimated, accuracyM). Reasons: POSTCODE_INVALID, POSTCODE_NOT_FOUND_CHECK, POSTCODE_NOT_NIPOST.

Parameters

Name	In	Type	Description
`code`	path	`string`	Required.
`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/postcodes/LA08A09DB09" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/postcodes/LA08A09DB09', {
  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/postcodes/LA08A09DB09",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

The postcode

Field	Type	Description
`code`	`string`	Required.
`display`	`string`	Required.
`components`	`PostcodeComponents`	Required.
`components.state`	`string`	Required.
`components.stateName`	`string`
`components.lga`	`string`	Required.
`components.lgaName`	`string`
`components.district`	`string`	Required.
`components.area`	`string`	Required.
`components.building`	`string`	Required.
`location`	`Point`	Required.
`location.type`	`string`	Required.
`location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`name`	`string`
`address`	`string`
`buildingType`	`string`
`entrances`	`Entrance[]`	Required. Verified first, main first: route to the first.
`entrances[].location`	`Point`	Required.
`entrances[].location.type`	`string`	Required.
`entrances[].location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`entrances[].kind`	`string`	Required. One of: `main`, `gate`, `pedestrian`, `service`.
`entrances[].verified`	`boolean`	Required.
`plusCode`	`string`	Required.
`country`	`string`	Required.
`source`	`string`	Required. One of: `nipost`, `osm`, `user`, `estimate`.
`estimated`	`boolean`	Required.
`accuracyM`	`number`
`distanceM`	`number`	Reverse geocoding: from the point asked about.
`attribution`	`string`	Required.

200 OK

{
  "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": [
          0
        ]
      },
      "kind": "main",
      "verified": true
    }
  ],
  "plusCode": "string",
  "country": "string",
  "source": "nipost",
  "estimated": true,
  "accuracyM": 0,
  "distanceM": 0,
  "attribution": "string"
}

Errors

default Error

Up to 100 NIPOST postcodes at once

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

Each code counts as one geocode call. An answer per code, in order, with its own error when it has one. Reasons (whole call) CODES_INVALID.

Parameters

Name	In	Type	Description
`fields`	query	`string`	Comma list of the fields to keep in each result (`a.b` reaches into objects; `id` is always kept; `*` = all).

Request body

Field	Type	Description
`codes`	`string[]`	Required. At least 1 items, at most 100 items.

cURL

curl -X POST "https://nways.ng/maps/v1/postcodes/batch" \
  -H "X-NWays-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"codes":["LA08A09DB09","FC 02 A09 DB 09"]}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/postcodes/batch', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "codes": [
      "LA08A09DB09",
      "FC 02 A09 DB 09"
    ]
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/postcodes/batch",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"codes": ["LA08A09DB09", "FC 02 A09 DB 09"]},
    timeout=10,
)
data = res.json()

Response

One result per code

Field	Type	Description
`results`	`object[]`	Required.
`results[].query`	`string`	Required.
`results[].postcode`	`Postcode`
`results[].postcode.code`	`string`	Required.
`results[].postcode.display`	`string`	Required.
`results[].postcode.components`	`PostcodeComponents`	Required.
`results[].postcode.components.state`	`string`	Required.
`results[].postcode.components.stateName`	`string`
`results[].postcode.components.lga`	`string`	Required.
`results[].postcode.components.lgaName`	`string`
`results[].postcode.components.district`	`string`	Required.
`results[].postcode.components.area`	`string`	Required.
`results[].postcode.components.building`	`string`	Required.
`results[].postcode.location`	`Point`	Required.
`results[].postcode.location.type`	`string`	Required.
`results[].postcode.location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`results[].postcode.name`	`string`
`results[].postcode.address`	`string`
`results[].postcode.buildingType`	`string`
`results[].postcode.entrances`	`Entrance[]`	Required. Verified first, main first: route to the first.
`results[].postcode.entrances[].location`	`Point`	Required.
`results[].postcode.entrances[].kind`	`string`	Required. One of: `main`, `gate`, `pedestrian`, `service`.
`results[].postcode.entrances[].verified`	`boolean`	Required.
`results[].postcode.plusCode`	`string`	Required.
`results[].postcode.country`	`string`	Required.
`results[].postcode.source`	`string`	Required. One of: `nipost`, `osm`, `user`, `estimate`.
`results[].postcode.estimated`	`boolean`	Required.
`results[].postcode.accuracyM`	`number`
`results[].postcode.distanceM`	`number`	Reverse geocoding: from the point asked about.
`results[].postcode.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",
      "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": []
        },
        "name": "string",
        "address": "string",
        "buildingType": "string",
        "entrances": [
          {}
        ],
        "plusCode": "string",
        "country": "string",
        "source": "nipost",
        "estimated": true,
        "accuracyM": 0,
        "distanceM": 0,
        "attribution": "string"
      },
      "error": {
        "code": 0,
        "reason": "string",
        "message": "string"
      }
    }
  ],
  "attribution": "string"
}

Errors

default Error

A GhanaPost GPS address

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

Where a GhanaPost GPS digital address is: mapped in OpenStreetMap or published by its owner, else (in districts where the method has been checked) estimated from the codes mapped around it (estimated, accuracyM). Never calls Ghana Post. Reasons: GHANAPOST_INVALID, GHANAPOST_UNKNOWN.

Parameters

Name	In	Type	Description
`code`	path	`string`	Required.
`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/ghanapost/GA-183-8164" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/ghanapost/GA-183-8164', {
  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/ghanapost/GA-183-8164",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

The address

Field	Type	Description
`id`	`string`	Required.
`name`	`string`	Required.
`type`	`string`	Required. address, street, business, landmark, building, postcode, ghanapost, or an area: neighbourhood, suburb, village, town, city, state…
`category`	`string`
`location`	`Point`	Required.
`location.type`	`string`	Required.
`location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`bbox`	`number[]`	west, south, east, north (areas) At least 4 items, at most 4 items.
`formattedAddress`	`string`
`postcode`	`string`	NIPOST postcode, compact
`ghanaPost`	`string`
`plusCode`	`string`	Required.
`country`	`string`
`distanceM`	`number`	From near (or the point asked about).
`estimated`	`boolean`	The point is an estimate, within accuracyM.
`accuracyM`	`number`
`placeId`	`string`	A business: its id for /places/{id}.
`attribution`	`string`

200 OK

{
  "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"
}

Errors

default Error

A Plus Code's area and what's there

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

A full Plus Code (6FR5J975+P4W), or a short one with a reference: near=lat,lng, or a town after it (J975+P4 Ikeja, URL-encoded). The answer is the reverse geocoding of the code's centre, with the full code and its bounds. Reasons: PLUSCODE_INVALID, PLUSCODE_SHORT, LOCALITY_NOT_FOUND, NEAR_INVALID.

Parameters

Name	In	Type	Description
`code`	path	`string`	Required.
`near`	query	`string`	lat,lng: rank and pick results near it.
`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/pluscodes/6FR5J975%2BP4W" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/pluscodes/6FR5J975%2BP4W', {
  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/pluscodes/6FR5J975%2BP4W",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

The code's area

Field	Type	Description
`location`	`Point`	Required.
`location.type`	`string`	Required.
`location.coordinates`	`number[]`	Required. [lng, lat] At least 2 items, at most 2 items.
`plusCode`	`string`	Required.
`country`	`Area \| null`	Required.
`region`	`Area \| null`	Required.
`formattedAddress`	`string`
`postcode`	`Postcode \| null`	Required. Nigeria: the building's NIPOST postcode, when one is within reach.
`ghanaPost`	`string \| null`	Required. Ghana: the nearest known GhanaPost GPS address (within 100 m).
`nearest`	`Result \| null`	Required.
`attribution`	`string`	Required.
`bounds`	`number[]`	Required. west, south, east, north At least 4 items, at most 4 items.

200 OK

{
  "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": {
          "type": "string",
          "coordinates": []
        },
        "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
  ]
}

Errors

default Error