Your First AfriHex Request

The business problem

Before evaluating any specific product, a new integration needs to answer one question: can I reliably get a request in and a response out? This guide is that five-minute check — get a key, make one call, read the response, and know what to do when it fails. The full search → normalize → encode → validate → save journey (what to actually build) lives in the Quickstart; this guide focuses on the mechanics and the failure modes the Quickstart doesn't dwell on.

What AfriHex returns

Every /v2/* response shares one envelope, success or failure:

{ "success": true, "data": { }, "meta": { "request_id": "…", "cached": false, "latency": "12.3ms" } }

{ "success": false, "error": { "code": "…", "message": "…" }, "meta": { "request_id": "…" } }

success tells you which shape you got without needing the HTTP status code — check it first. See Responses for the full envelope reference.

Before you begin

• Sign up for a key (POST /v2/self/signup) — it's emailed to you once, so store it in a secrets manager or .env file immediately, not in code.
• Every /v2/* call needs the key in an X-API-Key header — there's no query-parameter or Bearer-token alternative.
• You're on the Free tier by default: 100 requests/24h — enough to integrate, not to load-test. See Rate Limits.

Copyable request

export AFRIHEX_API_KEY="your-api-key"

curl "https://api.afrihex.com/v2/hexcode?lat=5.6037&lng=-0.1870&res=7" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

Full example response

{
  "success": true,
  "data": {
    "code": "AF-GH-7-0GXTQD5RFZZZZ",
    "h3_index": "877576970ffffff",
    "resolution": 7,
    "country": "Ghana",
    "country_code": "GH",
    "center": { "lat": 5.604078493411575, "lng": -0.19529195005881006 },
    "area_km2": 3.86
  },
  "meta": { "request_id": "c86825f0-d8ca-4ae1-8226-514cc48e05c0", "cached": false, "latency": "1.8ms" }
}

Field-by-field explanation

Field	Meaning
success	Branch on this before anything else — true/false, always present
data	The payload — shape is documented per endpoint, absent on error
error.code	Present only on failure — a stable string, branch on this, not error.message
meta.request_id	A UUID identifying this exact request — include it verbatim in any support ticket
meta.cached	true if served from cache — useful for debugging unexpectedly-fast or stale-looking responses
meta.latency	Server-side processing time — not round-trip time, won't include your network hop

Error and edge cases

The errors you'll actually hit in the first hour of integrating:

HTTP	error.code	Cause	Fix
401	MISSING_API_KEY	No X-API-Key header sent	Add the header to every request, not just some
401	INVALID_API_KEY	Key is wrong, revoked, or malformed	Re-check the value; generate a new key if it was revoked
400	INVALID_COORDINATES	Missing or non-numeric lat/lng	Validate client-side before sending
400	OUT_OF_BOUNDS	Coordinate is outside Ghana	Not a bug — the platform only covers the configured country today
404	NOT_FOUND	A well-formed input just doesn't resolve (e.g. an unindexed address)	Treat as a normal outcome, not an error — see Responses
429	RATE_LIMITED	You've exceeded your tier's quota	Back off until X-RateLimit-Reset — see Rate Limits, Retries, and Production Reliability
500/502	INTERNAL / UPSTREAM_ERROR	Server-side failure, not your request	Retry with backoff; if it persists, contact support with meta.request_id

Full error-code catalogue: Responses — Errors.

Production checklist

• The API key lives in an environment variable or secrets manager, never committed to source control.
• Every call checks success before reading data.
• Every call logs meta.request_id somewhere you can retrieve it later — it's the first thing support will ask for.
• 4xx errors are handled distinctly from 5xx — a 4xx means fix the request; a 5xx means retry.
• You've read Rate Limits, Retries, and Production Reliability before you ship anything that calls the API in a loop.

Related endpoints / next guide

• Quickstart — the full five-step address journey this guide assumes you'll build next.
• Choose the Right Location Identifier — what to actually send as "a location."
• Rate Limits, Retries, and Production Reliability — what changes once this is calling real traffic.