N-Ways
Developer docsGeocoding

Building with N-Ways?

Get an API key

Geocoding

Find any address, postcode or place in Nigeria, Ghana, Benin, Togo, Gabon, Côte d’Ivoire, Liberia, Guinea, Sierra Leone, Guinea-Bissau, Senegal, Cameroon, Burkina Faso, Cabo Verde and The Gambia, or say what’s at a spot on the map.

On this page

What it finds

Geocoding answers what people type, the way they type it, across Nigeria, Ghana, Benin, Togo, Gabon, Côte d’Ivoire, Liberia, Guinea, Sierra Leone, Guinea-Bissau, Senegal, Cameroon, Burkina Faso, Cabo Verde and The Gambia:

  • Places and areas: Osogbo, Oshogbo (a typo), Unilag (a nickname), Wuse 2.
  • Addresses and streets: 12 Allen Avenue, Ikeja, Rue des Cheminots, Lomé.
  • Businesses and landmarks: Shoprite Ikeja, Kejetia station, gare de Dantokpa.
  • NIPOST postcodes (Nigeria), down to the building where N-Ways knows it.
  • N-Ways home codes, the name of a quarter or village and a number, in any of their forms (by country).
  • GhanaPost GPS addresses like GA-183-8164, and Plus Codes like 6FR5J975+P4W.

Base address: https://nways.ng/maps/v1. Send your key in the X-NWays-Api-Key header, or as key= in a web page. Every answer is in the reference.

Find a place

GET /maps/v1/geocode

ParameterDescription
qRequired. What to find, up to 200 characters.
nearlat,lng: where the person is, or the map’s centre. Nearer results rank first, and categories (pharmacy, fuel) are searched around it.
countryOnly in these countries: NG, GH, BJ, TG, GA, CI, LR, GN, SL, GW, SN, CM, BF, CV, comma-separated.
limit1 to 20 results; 8 if not given.
langen or fr.
fieldsOnly these fields of each result, comma-separated: name,location. Smaller answers on slow networks.
cURL
curl "https://nways.ng/maps/v1/geocode?q=Ikeja+City+Mall&near=6.5244,3.3792&limit=3" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"
JavaScript
import { createClient } from '@nways/maps'

const nways = createClient({ key: process.env.NWAYS_API_KEY })
const { results } = await nways.geocode('Ikeja City Mall', { near: { lat: 6.5244, lng: 3.3792 }, limit: 3 })
const [lng, lat] = results[0].location.coordinates
Python
import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/geocode",
    params={"q": "Ikeja City Mall", "near": "6.5244,3.3792", "limit": 3},
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
results = res.json()["results"]
200 OK
{
  "results": [
    {
      "id": "osm:w568367632",
      "name": "Ikeja City Mall",
      "type": "landmark",
      "category": "shopping",
      "location": { "type": "Point", "coordinates": [3.357831, 6.61437] },
      "formattedAddress": "Ikeja, Lagos",
      "plusCode": "6FR5J975+P4W",
      "country": "NG",
      "attribution": "© OpenStreetMap contributors, N-Ways"
    }
  ],
  "attribution": "© OpenStreetMap contributors, N-Ways"
}

Result fields

FieldDescription
idThe result’s ID. Stable: you may store it and look the place up again.
nameIts name, or the address or code as written.
typeWhat it is: country, state, city, town, suburb, street, address, landmark, business, building, postcode…
categoryFor a business or landmark: pharmacy, petrol, bank… (the Places categories).
locationA GeoJSON point: coordinates are [longitude, latitude].
formattedAddressWhere it is, to tell places apart: Ikeja, Lagos.
postcode, ghanaPost, plusCodeIts NIPOST postcode, GhanaPost GPS address and Plus Code, where they apply. Every result has a Plus Code.
countryNG, GH, BJ, TG, GA, CI, LR, GN, SL, GW, SN, CM, BF or CV.
bboxFor areas: [west, south, east, north], to fit the map to.
distanceMFrom near, in a straight line.
estimated, accuracyMThe point is an estimate (a postcode placed from the codes around it), within about accuracyM metres.
placeIdFor a business: its ID for place details.
attributionThe credit to show with this result.

Fields with nothing to say are left out, and new fields may be added: ignore the ones you don’t know. When nothing matches but something close does, the answer has didYouMean.

What’s here (reverse geocoding)

GET /maps/v1/reverse?lat=…&lng=… answers in one shape in all fifteen countries: the country and region (with French names), the point’s plusCode, a one-line formattedAddress, in Nigeria the building’s NIPOST postcode within reach, in Ghana the nearest known ghanaPost address, and the nearest named address, street or landmark within radius metres (200 by default, 10 to 1,000).

cURL
curl "https://nways.ng/maps/v1/reverse?lat=6.4474&lng=3.4720" -H "X-NWays-Api-Key: YOUR_API_KEY"
200 OK (shortened)
{
  "location": { "type": "Point", "coordinates": [3.472, 6.4474] },
  "plusCode": "6FR5CFWC+XR6",
  "country": { "code": "NG", "name": "Nigeria", "nameFr": "Nigéria" },
  "region": { "code": "NG-LA", "name": "Lagos State", "nameFr": "État de Lagos" },
  "formattedAddress": "12 Admiralty Way, Lekki, Lagos State, Nigeria",
  "postcode": { "code": "LA08A09DB09", "display": "LA 08 A09 DB 09", "entrances": ["…"] },
  "ghanaPost": null,
  "nearest": { "name": "…", "type": "landmark", "distanceM": 6 }
}

NIPOST postcodes

Nigeria’s building postcodes name a building, not just an area. GET /maps/v1/postcodes/{code} takes any written form (LA 08 A09 DB 09, la-08-a09-db-09):

cURL
curl "https://nways.ng/maps/v1/postcodes/LA08A09DB09" -H "X-NWays-Api-Key: YOUR_API_KEY"

The answer has the building’s location, its address where known, the code’s display form and components (state, LGA, district, area, building, with the state and LGA names), and its entrances: the gates and doors people really use, verified ones first. Route to the first entrance, not the middle of the building; or give { "postcode": "…" } to Routes and it does it for you. A valid code N-Ways hasn’t placed yet comes back estimated, from the codes around it, with accuracyM.

POST /maps/v1/postcodes/batch looks up to 100 codes at once (each counts as one call), for cleaning a customer list.

GhanaPost GPS addresses and Plus Codes

cURL
curl "https://nways.ng/maps/v1/ghanapost/GA-183-8164" -H "X-NWays-Api-Key: YOUR_API_KEY"
curl "https://nways.ng/maps/v1/pluscodes/6FR5J975+P4W" -H "X-NWays-Api-Key: YOUR_API_KEY"

A GhanaPost GPS address comes from OpenStreetMap or its owner, or, in districts where it has been checked, is estimated from the codes mapped around it (estimated). N-Ways never calls Ghana Post. An address it can’t place answers 404 GHANAPOST_UNKNOWN: ask for a landmark or a Plus Code instead.

Plus Codes work everywhere, even where there’s no address. A short code needs a reference: near=lat,lng, or a town after it (J975+P4 Ikeja).

Home codes

Every compound in these 12 countries has an N-Ways home code: the name of its quarter or village and a short number, like the ones below. The geocoding call takes them as typed, and each country’s guide covers lookups, codes at a point and offline decoding. The codes, the engine and a ready-made server are open on GitHub, so you can also host them yourself.

  • Autocomplete: suggestions while people type.
  • Address validation: check and complete an address before you dispatch.
  • Errors: QUERY_REQUIRED, POSTCODE_INVALID, POSTCODE_NOT_FOUND_CHECK and the others.

The earlier addresses

Partners who started with https://nways.ng/v1/geocode, /v1/reverse, /v1/postcodes and /v1/ghanapost: those keep working for at least 12 months, but their answers can change with the N-Ways app. Move to /maps/v1, whose answers only ever gain fields. Changelog