Skip to main content

Quickstart

This guide gets you from zero to a saved, quality-checked location in under five minutes. The flow below — search → normalize → encode → validate → save — is the default journey for almost any integration, from a weekend project to a production pipeline. Nothing in it needs a Banking Suite key, consent, or KYC; those matter once you need to trust or track a location, not before (see Products when you get there).

1. Get an API key​

Sign up for a free-tier key with one request. No password needed — the key is returned once and emailed to you, so keep it safe.

curl -X POST "https://api.afrihex.com/v2/self/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "name": "Your App",
    "organization": "Your Company"
  }'

You'll receive a key in the response, or visit the developer dashboard to create additional keys.

2. Set the key as an environment variable​

export AFRIHEX_API_KEY="your-api-key"

3. Search a place, or resolve an address you already have​

Every /v2/* endpoint authenticates with the X-API-Key header. Start from whichever side of the problem your user gives you:

A user typed a place name — search for it:

curl "https://api.afrihex.com/v2/search?q=Accra%20Mall" \
  -H "X-API-Key: $AFRIHEX_API_KEY"
{
  "success": true,
  "data": {
    "query": "Accra Mall",
    "count": 2,
    "results": [
      {
        "type": "place",
        "name": "Accra Mall, Airport Bypass, Accra, Ghana",
        "gps_name": "GL1524944",
        "region": "Greater Accra",
        "district": "La Dade Kotopon",
        "latitude": 5.6221843,
        "longitude": -0.1729361
      }
    ]
  }
}

Or you already have a digital address — a GhanaPostGPS code like GA-142-7281 — skip search entirely and go straight to step 4, since /v2/lookup does both steps in one call.

4. Retrieve normalized coordinates and administrative context​

A search hit gives you coordinates and a gps_name, but not a quality score yet. Resolve it (or the address you already had) to get the fully normalized record:

curl "https://api.afrihex.com/v2/lookup?address=GL1524944" \
  -H "X-API-Key: $AFRIHEX_API_KEY"
{
  "success": true,
  "data": {
    "gps_name": "GL1524944",
    "region": "Greater Accra",
    "district": "La Dade Kotopon",
    "area": "Shiashie",
    "postcode": "GL152",
    "street": "Airport Bypass",
    "center_latitude": 5.6221843,
    "center_longitude": -0.1729361,
    "quality_score": 0.92,
    "quality_tier": "high",
    "provenance": {
      "source": "third_party_match",
      "provider": "ghanapostgps",
      "confidence": 0.9
    }
  }
}

Have raw GPS coordinates instead of a digital address? GET /v2/reverse?lat=…&lng=… returns the identical shape — see Addresses & Geocoding.

5. Generate the AfriHex code​

Feed the normalized coordinates into the hex encoder:

curl "https://api.afrihex.com/v2/hexcode?lat=5.6221843&lng=-0.1729361&res=7" \
  -H "X-API-Key: $AFRIHEX_API_KEY"
{
  "success": true,
  "data": {
    "code": "AF-GH-7-0GXTQD5VJZZZZ",
    "h3_index": "877576962ffffff",
    "resolution": 7,
    "country": "Ghana",
    "country_code": "GH",
    "center": { "lat": 5.622167, "lng": -0.172950 },
    "area_km2": 3.86
  }
}

That's a stable, shareable identifier for the location — see the hex-code contract for exactly what it guarantees.

6. Validate location quality​

Read quality_score (0.0–1.0) or the coarser quality_tier off the step-4 response before you rely on the match:

  • ≥ 0.8 (high) — strong enough to use as-is.
  • 0.5 – 0.8 (medium) — usable, but worth corroborating for anything high-stakes.
  • < 0.5 (low) — sparse; consider it a starting point, not a final answer.

If all you have is a raw address string and want a cheap format check before spending a lookup call on it, GET /v2/validate?address=… tells you whether it's even well-formed.

7. Save the result with confidence and source metadata​

Persist the hex code and coordinates alongside quality_score/quality_tier and the provenance object, so anyone reading the row later can tell how much to trust it without re-querying the API:

{
  "hex_code": "AF-GH-7-0GXTQD5VJZZZZ",
  "lat": 5.6221843,
  "lng": -0.1729361,
  "region": "Greater Accra",
  "district": "La Dade Kotopon",
  "quality_score": 0.92,
  "quality_tier": "high",
  "provenance": { "source": "third_party_match", "provider": "ghanapostgps", "confidence": 0.9 }
}

provenance.source from /v2/lookup and /v2/reverse always reads third_party_match — both are matched against a single registry (GhanaPostGPS), not confirmed on the ground. The field is still worth storing: the same shape carries genuinely different tiers (device_gps, user_confirmed, agent_verified) once a location comes from your own app's GPS or from a verification flow — see Identity & KYC.

What else Addresses & Geocoding can do​

  • GET /v2/search/autocomplete — type-ahead suggestions as the user types.
  • POST /v2/bulk/validate / POST /v2/bulk/reverse — up to 1,000 at a time.
  • POST /v2/address/parse — decompose a relative, free-text Ghanaian address ("Adjacent Goil, behind Kejetia Market") into structured components.
  • GET /v2/nearby — other locations within a radius.

See Addresses & Geocoding for the full guide.

When you need more than an address​

The five steps above cover AfriHex Locate end to end. Two more products build on top of it, and neither is needed to ship a basic address feature:

Using the TypeScript SDK​

If you use Node.js, the official SDK (@afrihex/sdk) is coming soon — see the SDK guide for its full surface. Once published, you'd use it like this:

npm install @afrihex/sdk   # available soon
import { AfriHex } from '@afrihex/sdk'

const afrihex = new AfriHex({
  apiKey: process.env.AFRIHEX_API_KEY!,
})

const hex = await afrihex.hex.encode(5.6221843, -0.1729361, 7)
console.log(hex.code) // "AF-GH-7-0GXTQD5VJZZZZ"

See the SDK guide for the full API surface.

Next steps​