Senegal home codes

Every compound in Senegal has a home code. Look one up, find the code at a point, or decode it offline with the open engine, and credit N-Ways where you show it.

On this page

What a home code is
Look up a code
What’s the code here?
Search
Decode offline
Host it yourself

What a home code is

Every compound in Senegal, in all 46 zones, has an N-Ways home code: the short name of its quartier, village or cité and a short number, such as Ouakam 2512 or Touba Mosquée 22 950. Each code is unique in the whole country on its own and leads to the compound’s gate. Codes start provisional and become confirmed when residents agree in the N-Ways app.

Remembered form, what people say and type: Ouakam 2512. Any case or accents, French or Wolof spellings (Wakam 2512), with or without the spaces.
Written form, on plates and forms: OUAKAM 2512 · DAKAR (the zone added). People never see or type a check letter; it is in the canonical form only.
Canonical form, for systems, QR codes and links: SN-DKR-0080-2512-J (zone, place index, number, check letter). People never need it.
Spot codes name any point with no compound, computed offline on the UTM 28N grid: DKR 5553 1512.

The model, the engine and the registry of every address are open: github.com/n-ways/open-addresses-senegal. The white paper explains every rule.

Note:

Credit N-Ways wherever you show a code. Show “Home code by N-Ways Addressing” next to codes in your app, and credit “N-Ways Addressing for Senegal, © N-WAYS LIMITED (nways.ng)” with a link to the repository in your about screen or documentation. The engine is Apache 2.0, the data ODbL 1.0 and the papers CC BY 4.0.

Look up a code

GET https://map.nways.ng/v1/homecodes/{code}, where code is any of the forms above, URL-encoded. No key is needed.

cURL

curl "https://map.nways.ng/v1/homecodes/Ouakam%202512"

200 OK

{
  "country": "SN",
  "home": "Ouakam 2512",
  "machine": "SN-DKR-0080-2512-J",
  "name": "Ouakam",
  "nameProvisional": false,
  "municipality": "Dakar",
  "fullLine": "OUAKAM 2512 · DAKAR",
  "spoken": "Ouakam, vingt-cinq, douze",
  "status": "provisional",
  "issued": "bulk",
  "entrance": { "lat": 14.7247067, "lng": -17.4849374, "kind": "centre", "source": "map" },
  "location": { "lat": 14.7247067, "lng": -17.4849374 },
  "plusCode": "7C64PGF8+V2P",
  "lote": { "use": "residential", "class": "res.maison", "kind": "un_batiment", "structures": 1, "floorAreaM2": 32.7, "enclosed": false },
  "credit": "N-Ways Addressing for Senegal, © N-WAYS LIMITED (nways.ng)",
  "creditUrl": "https://github.com/n-ways/open-addresses-senegal"
}

Field	Description
`home`, `machine`	The remembered and canonical forms. Show `home` to people; store `machine`.
`fullLine`	The written form, as on a plate: with the zone. The check letter is in the canonical form, for systems only.
`officialName`	The place’s full name, for small print (S.I.C.A.P. Liberté Six for `Liberté 6`). Missing when it equals `name`.
`coverage`, `officialAddress`	Where the commune numbered the door: `official` and its address as written (show it first, the code beside it); `official-pending` in quartiers of the municipal addressing programme whose door numbers aren’t shared yet. Missing elsewhere.
`nameProvisional`	The commune still has to choose the short name. The number never changes; the name may change once.
`status`	`provisional`, `confirmed` (residents agreed) or `retired` (no home there any more; the number is never reused).
`entrance`, `location`	Where to go: the gate when it is mapped, else the compound’s main building. Route to this point.
`postcode`	La Poste’s postcode, only where it is mapped, for context. It is never derived from the code.
`lote`, `structures`	The compound and each building’s profile: class (`res.maison`, `com.boutique`…), size, floors, status, each with its source. Homes never carry anything about the people who live there.

Errors: 400 homecode_format when the text isn’t a code; 404 homecode_unknown with a message saying why (a name no place has, a number outside every block, a wrong check letter).

What’s the code here?

GET https://map.nways.ng/v1/homecodes/at?lat=…&lng=… answers for a point: "status": "found" with the code, or "none" where no compound has one yet.

cURL

curl "https://map.nways.ng/v1/homecodes/at?lat=14.7247&amp;lng=-17.4849"

Search

A code typed into N-Ways search, in any of its forms, finds the compound’s gate as the first result, with "category": "homecode" and the credit in attribution.

Decode offline

The repository’s reference engine (Python, standard library only) decodes every form, checks the check letter and encodes and decodes spot codes with no network: python3 engine/reference/sn_engine.py find "Ouakam 2512". Its test vectors are the conformance test for your own implementation, and registry/ holds every issued address, one gzip file per zone.

Host it yourself

You can serve Senegal’s codes from your own servers, with no calls to N-Ways. The repository on GitHub holds every issued code (registry/), the code areas and the model (model/), the reference engine, and a ready-made registry server with its JSON API:

Shell

git clone https://github.com/n-ways/open-addresses-senegal
cd open-addresses-senegal
docker compose up -d

The server imports the registry on first start, then answers lookups and searches on your machine; server/README.md covers configuration, backups and updates, and docs/api.md every endpoint. Your copy is read-only: new codes come from one issuer per country, N-Ways unless the State designates another, so no number is ever given twice. Pull the repository again for the codes issued since.

What you take	Licence	What it asks of you
The engine, the server and the tools	Apache 2.0	Keep the licence and `NOTICE` when you ship or change them.
The codes, the areas and the model (`registry/`, `model/`, `engine/data/`)	ODbL 1.0	Credit “N-Ways Addressing for Senegal, © N-WAYS LIMITED (nways.ng)”, linked to the repository, where you show the codes. A database you make from the data and share is shared under ODbL 1.0 too.
The papers and other documents (`docs/`)	CC BY 4.0	Credit N-Ways and say what you changed.

The full terms, and the credit line for maps and datasets made from the data (it also names OpenStreetMap), are in LICENSING.md. You may say your product uses N-Ways Addressing, not that it is N-Ways or is endorsed by N-Ways.