N-WaysCabo Verde home codes
Every building in Cabo Verde 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
Every building in Cabo Verde, on every island, has an N-Ways home code: the short name of its bairro, zona or povoação and a short number, such as Palmarejo 12 34 or João Vaz 214. Each code is unique in the whole country on its own and leads to the lote’s gate or front door. Codes start provisional and become confirmed when residents agree in the N-Ways app.
- Home form, what people say and type:
Palmarejo 12 34. Any case, with or without the spaces. - Machine form, for systems, plates and links:
PR-0973-1234-0(municipality, national name index, number, check digit). - The official name (Palmarejo Grande) and the Correios postcode come with every code as context. They are never part of it.
The model, the engine and the data are open: github.com/n-ways/open-addresses-cabo-verde. The white paper explains every rule.
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 Cabo Verde, © 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 the machine form or the home form, URL-encoded. No key is needed.
curl "https://map.nways.ng/v1/homecodes/Palmarejo%2012%2034"{
"country": "CV",
"home": "Palmarejo 12 34",
"machine": "PR-0973-1234-0",
"check": 0,
"name": "Palmarejo",
"officialName": "Palmarejo Grande",
"nameProvisional": true,
"municipality": "Praia",
"island": "Santiago",
"postcode": { "value": "7600", "kind": "area", "source": "Correios de Cabo Verde (UPU 2014)" },
"fullLine": "Palmarejo 12 34 · Palmarejo Grande · Praia, Santiago · 7600",
"spoken": "Palmarejo, doze, trinta e quatro",
"status": "provisional",
"issued": "bulk",
"entrance": { "lat": 14.9201, "lng": -23.5402, "kind": "door", "source": "map" },
"location": { "lat": 14.9201, "lng": -23.5402 },
"plusCode": "796RWFC5+2WV",
"lote": { "use": "residencial", "structures": 1, "floorAreaM2": 120, "enclosed": false },
"credit": "Home code by N-Ways Addressing",
"creditUrl": "https://github.com/n-ways/open-addresses-cabo-verde"
}| Field | Description |
|---|---|
home, machine | The two forms of the code. Show home to people; store machine. |
officialName | The zone’s full name, for small print. Missing when it equals name. |
coverage, officialAddress | Where the Câmara numbered the street: official and its address as written (show it first, the code beside it); official-pending in historic centres whose register isn’t shared yet. Missing elsewhere. |
nameProvisional | The Câmara Municipal 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 or door. Route to this point, not to the building’s centre. |
postcode | The Correios postcode of the area, for context. It is never derived from the code. |
lote, structures | The building profile: use, 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 home code; 404 homecode_unknown with a message saying why (a name no zone 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 building has one yet. Every building has a code, the officially numbered ones too: where a Câmara has numbered the street, the code carries "coverage": "official" and the municipality’s address in officialAddress, exactly as written, to show first; in the historic centres whose register the Câmara keeps (the Platô, central Mindelo), "coverage": "official-pending". The registry files carry the same in their coverage and official_address columns.
curl "https://map.nways.ng/v1/homecodes/at?lat=14.9201&lng=-23.5402"Search
A home code typed into N-Ways search, in any case and with or without spaces, or a machine form, finds the lote’s gate or door as the first result, with "category": "homecode" and the credit in attribution.
Decode offline
The repository’s reference engine (Python, standard library only) parses home and machine forms, checks the check digit and decodes a code to its zone with no network: python3 engine/reference/cv_engine.py "Palmarejo 12 34". Its test vectors are the conformance test for your own implementation.
Host it yourself
You can serve Cabo Verde’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-cabo-verde
cd open-addresses-cabo-verde/server
docker compose up -dThe 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 Cabo Verde, © 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.