Skip to main content

Choose the Right Location Identifier

The business problem​

Every AfriHex endpoint asks for "a location," but the platform actually has five distinct kinds of location identifier, and picking the wrong one for the job is the single most common early integration mistake — storing a hex code where you needed a stable per-visit pin, or showing a customer a raw coordinate where they expected something they could read back to you over the phone.

They aren't interchangeable, and they aren't a precision ladder from "rough" to "exact" — each one answers a different question:

IdentifierAnswersExample
CoordinateWhere, exactly, right now?5.6221843, -0.1729361
Digital address (GhanaPostGPS)What's the shareable, human-readable address here?GA-142-7281
AfriHex codeWhat grid cell is this in, at a given zoom level?AF-GH-7-0GXTQD5VJZZZZ
LandmarkWhat do people actually call this place?"Kwame Nkrumah Circle"
Structure pointWhere's the actual door/gate for this cell?{ lat, lng, label: "main gate" }, tied to a hex code

:::note No place_id or building_id today If you're coming from Google Places or Mapbox, you might expect a generic place_id or a building_id. AfriHex doesn't have either as a standalone, stable identifier — a landmark is the closest analogue to a place ID (see Search Informal Landmarks and Local Aliases), and a building is handled as footprint-snapping evidence (building_edge precision), not an addressable ID — see Hex Addressing's five things that aren't the same. Don't design a schema around a field that doesn't exist; use the hex code or digital address as your primary key instead. :::

What AfriHex returns​

IdentifierStabilityPrecisionSourceResolve it back via
CoordinateNot stable — depends on GPS/device, can driftA point, as exact as the fixDevice GPS, a geocoder, a field surveyGET /v2/reverse?lat=&lng=
Digital addressStable — assigned once by GhanaPostGPS~small block/precinctGhanaPostGPS's registryGET /v2/lookup?address=
AfriHex codeStable — deterministic from a coordinate + resolutionA cell, area scales with resolution (see Cell size by resolution)Pure H3 math, always available in-countryGET /v2/hexcode/{code}
LandmarkSemi-stable — can be renamed, merged, or reported wrongA point (best-known)AfriHex's landmark databaseGET /v2/landmarks/geocode?q=
Structure pointStable once surveyed, tied to one hexA point, survey-confirmedField survey, promoted via POST /v2/admin/structure-points/promoteGET /v2/address/resolve?hex=

Before you begin​

  • An API key (see Quickstart).
  • Decide what your system of record actually needs to store long-term. A hex code and a digital address are both stable primary keys; a raw coordinate is not — don't key a database row on a coordinate that will never repeat.
  • Know which direction you're converting: coordinate → identifiers (forward), or identifier → coordinate (reverse). Every row below has a reverse-geocode counterpart.

Copyable request​

The most common conversion — a coordinate to everything else at once:

curl "https://api.afrihex.com/v2/reverse?lat=5.6221843&lng=-0.1729361" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

Full example response​

{
  "success": true,
  "data": {
    "gps_name": "GL1524944",
    "address": "GL1524944",
    "region": "Greater Accra",
    "district": "La Dade Kotopon",
    "area": "Shiashie",
    "postcode": "GL152",
    "center_latitude": 5.6221843,
    "center_longitude": -0.1729361,
    "quality_score": 1,
    "quality_tier": "high",
    "provenance": { "source": "third_party_match", "provider": "ghanapostgps", "confidence": 0.95 }
  }
}

Note what's not in this response: no hex code. Reverse geocoding and hex encoding are separate calls on purpose (see Choosing a resolution before you encode) — chain in GET /v2/hexcode?lat=…&lng=…&res=7 yourself, exactly as the Quickstart does.

Field-by-field explanation​

FieldIdentifier it belongs toNotes
gps_name / addressDigital addressThe canonical GhanaPostGPS code — use this as your shareable, typeable identifier
center_latitude / center_longitudeCoordinateThe point AfriHex actually matched, not necessarily where you queried from
region / district / area / postcodeDigital addressAdministrative context, not identifiers themselves — don't use area as a dedup key, it's not unique
quality_score / quality_tier—How complete the record is, not which identifier is "better" — see Understanding confidence and verification

Error and edge cases​

  • A coordinate resolves to a cell but no digital address. GET /v2/hexcode never fails inside Ghana (see the hex-code contract), but GET /v2/reverse can return 404 NOT_FOUND for a point GhanaPostGPS hasn't indexed. Treat that as normal — you still have a valid hex code, just no digital address yet.
  • Two different coordinates produce the same digital address. GhanaPostGPS cells aren't points; a small GPS jitter near a cell edge can also flip which cell you land in — see Behaviour near a cell boundary, which applies to both grid systems.
  • A landmark match isn't the coordinate you expected. Landmark names aren't unique (multiple "Shell" fuel stations exist) — always check alternate_landmarks/confidence in the geocoder response before trusting a single match; see Routing & Navigation.
  • A structure point doesn't exist for a hex. Most hex cells have no surveyed structure point — GET /v2/address/resolve?hex=… falls back to building_edge or hex_centroid precision instead of erroring. Read precision before you trust the point (see Hex Addressing's precision tiers).

Production checklist​

  • Store a stable identifier (hex code and/or digital address) as your primary key — never a raw coordinate.
  • Decide up front which resolution you'll use for hex codes, and keep it consistent (see Best practices).
  • Don't parse structure out of a digital address string client-side (region/district codes can be reassigned) — always read it from the API response fields.
  • For anything user-facing ("where is this?"), check precision via GET /v2/address/resolve?hex=… rather than assuming the hex centroid is a real point.

Related endpoints / next guide​