Togo home codes

What a code is

Every compound in Togo has an N-Ways code: the short name of its quartier, village or canton and a number of four or five digits, such as Fréau-Jardin 1058 or Zongo 14198. 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, type and write on plates: Fréau-Jardin 10 58, also without the space (Fréau-Jardin 1058) or with dots. Any case and the usual spellings (Djanta Copé = Djanta kopé, Lom-Nava = Lom Nava), the official name in place of the short one (Adjahun Fiagbe 1017 = Fiagbe 1017). People never see or type a check digit.
• Machine form, for systems, QR codes and links: TG-FRJ-1058-2 (the area, the number and a Damm check digit that catches every single wrong digit and every swap of two neighbouring digits; .2/1 after it for building 2, gate 1).
• Spot code, for any point: FRJ-54-4R, a cell of about 3.4 m framed on its quartier or canton; every card also carries its gate’s Plus Code (6FR346JF+P96).
• Lomé street codes such as 165 AMT are official street references, not N-Ways codes: the API says so and never decodes them.

In the former commune of Lomé the official street comes first, in officialAddress with "coverage": "official-street"; the District Autonome du Grand Lomé’s entrance address will take its place once it is released. No préfecture or commune is needed to decode a code; municipality is looked up from the position. The model, the engine and the registry of every code are open: github.com/n-ways/open-addresses-togo. The white paper explains every rule.

Look up a code

GET https://map.nways.ng/v1/homecodes/{code}, where code is the remembered or machine form, or a spot code on a compound, URL-encoded. No key is needed.

curl "https://map.nways.ng/v1/homecodes/TG-FRJ-1058-2"

{
  "country": "TG",
  "home": "Fréau-Jardin 1058",
  "machine": "TG-FRJ-1058-2",
  "check": 2,
  "name": "Fréau-Jardin",
  "coverage": "official-street",
  "officialAddress": "Rue Mission Tové, Lomé",
  "nameProvisional": false,
  "municipality": "Lomé",
  "fullLine": "Fréau-Jardin 10 58",
  "spoken": "Fréau-Jardin, 10 58",
  "status": "provisional",
  "issued": "bulk",
  "entrance": { "lat": 6.1317765, "lng": 1.2234008, "kind": "centre", "source": "map" },
  "location": { "lat": 6.1317765, "lng": 1.2234008 },
  "plusCode": "6FR346JF+P96",
  "lote": { "use": "residential", "kind": "building", "class": "residential", "structures": 1, "floorAreaM2": 19.5, "rule": "single", "official": "Rue Mission Tové, Lomé" },
  "credit": "N-Ways Addressing for Togo, © N-WAYS LIMITED (nways.ng)",
  "creditUrl": "https://github.com/n-ways/open-addresses-togo"
}

Errors: 400 homecode_format when the text isn’t a code (a Lomé street code says so); 404 homecode_unknown with a message saying why (a name no area has, a number in no block of its name).

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 "https://map.nways.ng/v1/homecodes/at?lat=6.13178&lng=1.22340"

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 machine form and reads and writes spot codes, with no network: python3 engine/reference/tg_engine.py parse "Fréau-Jardin 10 58". Its conformance vectors (engine/reference/vectors.json) are the test for your own implementation, engine/data/register.json holds every area and name with its frozen blocks, and registry/ every issued code, one gzip file per préfecture.

Host it yourself

You can serve Togo’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:

git clone https://github.com/n-ways/open-addresses-togo
cd open-addresses-togo/server
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.

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.