Skip to main content

Quickstart

Five minutes: resolve an address, create an account, register your own address, and mint an API key.

1. Resolve an address — no key needed​

Public resolution is open. Any of the three input forms works: canonical (ZM299224388), display (ZM-2992-24388), or with any spacing — the API normalizes and validates the check digit first.

curl https://api.adas.africa/v1/public/addresses/ZM-2992-24388
{
  "canonical": "ZM299224388",
  "display": "ZM-2992-24388",
  "country": "ZM",
  "country_name": "Zambia",
  "zone": "2992",
  "zone_name": "",
  "lat": -15.4167,
  "lng": 28.2833,
  "plus_code": "5GRGHJM7+899",
  "label": "First live address",
  "verification_level": 0,
  "created_at": "2026-07-11T00:29:31.517529Z"
}

plus_code is a derived Open Location Code (11 characters ≈ 3 m cell) — paste it into Google Maps for instant cross-referencing. The coordinates remain the source of truth.

A mistyped code fails before lookup — try changing the last digit and you'll get 400 BAD_CHECK_DIGIT, not someone else's address.

2. Create an account​

Registration is phone + password (see Authentication for why):

curl -X POST https://api.adas.africa/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"phone": "+260971234567", "password": "a-strong-passphrase"}'

The response includes an access JWT (30 min) and a refresh token (30 days).

3. Register an address​

POST a coordinate; the registry finds the zone, draws a random unit, computes the check digit, and mints the code:

curl -X POST https://api.adas.africa/v1/addresses \
  -H "Authorization: Bearer $ACCESS" \
  -H 'Content-Type: application/json' \
  -d '{"lat": -15.4167, "lng": 28.2833, "label": "Head office"}'
{
  "canonical": "ZM299225597",
  "display": "ZM-2992-25597",
  "zone": "2992",
  "qr_url": "https://adas.africa/a/ZM299225597",
  "...": "..."
}

A printable QR for any address is one GET away (public, SVG):

https://api.adas.africa/v1/addresses/{canonical}/qr.svg

4. Mint an API key for your systems​

curl -X POST https://api.adas.africa/v1/keys/ \
  -H "Authorization: Bearer $ACCESS" \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-backend", "mode": "test"}'

The full key (adas_test_…) appears once in this response — store it. Use it from your servers with the Api-Key scheme:

curl https://api.adas.africa/v1/addresses/ZM299224388 \
  -H "Authorization: Api-Key adas_test_..."

In JavaScript and Python​

const res = await fetch(
  "https://api.adas.africa/v1/public/addresses/ZM299224388",
);
const address = await res.json();
console.log(address.display, address.lat, address.lng);
import requests

address = requests.get(
    "https://api.adas.africa/v1/public/addresses/ZM299224388"
).json()
print(address["display"], address["lat"], address["lng"])

Next: understand how the codes work — especially the check digit, which your UI should validate client-side.