Guinea home codes

What a code is

Every compound in Guinea, in all five postal regions, has an N-Ways code: the short name of its quartier, town or village and a number of four or five digits, such as Hafia 3 · 1230 or Linsan 5389. 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: Hafia 3 · 1230, also typed in pairs (hafia 3 12 30). Any case and accents, the official name in place of the short one (Missidé Bhoundou Kalouma 1260 = Kalouma 1260). A name that ends in a number takes a · before the home’s number.
• Plate form, on plates and forms: HAFIA 3 · 1230. People never see or type a check digit; it is in the machine form only.
• Machine form, for systems, QR codes and links: GN-04261-1230-8 (the name’s national id, the number, the check digit; GN-04261-1230.2-3 for the compound’s second building).
• Spot code, for any 3 m square: 0 22JV PVQQ, computed offline; its first five characters, 0 22JV, are the 1.2 km bloc code.

No commune, préfecture or region is part of a code, so the 2024 and 2026 reforms change none; municipality is looked up from the position. In Kaloum, the official street of the national addressing programme comes first, in officialAddress. The model, the engine and the registry of every code are open: github.com/n-ways/open-addresses-guinea. The white paper explains every rule.

Look up a code

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

curl "https://map.nways.ng/v1/homecodes/GN-04261-1230-8"

{
  "country": "GN",
  "home": "Hafia 3 · 1230",
  "machine": "GN-04261-1230-8",
  "check": 8,
  "name": "Hafia 3",
  "nameProvisional": false,
  "municipality": "Dixinn, Conakry",
  "fullLine": "Hafia 3 · 1230 · Dixinn, Conakry",
  "spoken": "Hafia 3, douze trente",
  "status": "provisional",
  "issued": "bulk",
  "entrance": { "lat": 9.5682034, "lng": -13.6544537, "kind": "centre", "source": "map" },
  "location": { "lat": 9.5682034, "lng": -13.6544537 },
  "plusCode": "6CX8H89W+76M",
  "lote": { "use": "residential", "kind": "compound", "class": "residential.house", "structures": 2, "floorAreaM2": 206.4, "settlement": "town", "rule": "annex" },
  "credit": "N-Ways Addressing for Guinea, © N-WAYS LIMITED (nways.ng)",
  "creditUrl": "https://github.com/n-ways/open-addresses-guinea"
}

In Kaloum the card carries the official street first:

{
  "home": "Almamiya 1939",
  "machine": "GN-00053-1939-4",
  "coverage": "official-street",
  "officialAddress": "Avenue Dinah Salifou, Kaloum",
  "municipality": "Kaloum, Conakry",
  "fullLine": "Almamiya 1939 · Kaloum, Conakry"
}

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 digit).

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=9.56820&lng=-13.65445"

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 digit and computes spot and bloc codes, with no network: python3 engine/reference/gn_codes.py home "Hafia 3 · 1230". Its conformance vectors (engine/reference/vectors.json) are the test for your own implementation, engine/data/register.json holds every place and its frozen blocks, and registry/ every issued code, one gzip file per postal region.

Host it yourself

You can serve Guinea’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-guinea
cd open-addresses-guinea
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.