Addresses & Geocoding

Everything you need to turn addresses, coordinates, and place names into each other. This is the geocoding layer of the platform — GhanaPostGPS codes, reverse geocoding, place search, validation, and bulk operations.

tip

The same stack is forkable to other African countries via a country profile. For Ghana, the addressing provider resolves GhanaPostGPS codes like GA-142-7281.

Resolve a GPS code to coordinates

GET /v2/lookup?address=GA-142-7281

curl "https://api.afrihex.com/v2/lookup?address=GA-142-7281" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

{
  "success": true,
  "data": {
    "gps_name": "GA1427281",
    "address": "GA1427281",
    "region": "Greater Accra",
    "district": "Accra",
    "area": "West Ridge",
    "postcode": "GA142",
    "street": "Chief Brimah Street",
    "center_latitude": 5.547396933004167,
    "center_longitude": -0.207847593183683,
    "north_latitude": 5.54741945851821,
    "south_latitude": 5.54737447512249,
    "east_longitude": -0.207825240976392,
    "west_longitude": -0.207825240976392,
    "google_maps_url": "https://www.google.com/maps/search/?api=1&query=5.547397,-0.207848",
    "quality_score": 1
  }
}

404 NOT_FOUND is returned when a well-formed code doesn't resolve — treat that as a normal outcome, not an error.

Reverse geocode coordinates

GET /v2/reverse?lat=5.556&lng=-0.196

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

Coordinates outside the active country's bounds return 400 OUT_OF_BOUNDS.

Search by place name

GET /v2/search?q=Accra%20Mall

curl "https://api.afrihex.com/v2/search?q=Accra%20Mall" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

Each result carries coordinates and, where resolvable, the GhanaPostGPS code:

{
  "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",
        "area": "Shiashie",
        "postcode": "GL152",
        "latitude": 5.6221843,
        "longitude": -0.1729361,
        "google_maps_url": "https://www.google.com/maps/search/?api=1&query=5.622184,-0.172936"
      }
    ]
  }
}

For type-ahead, use GET /v2/search/autocomplete?q=accra&limit=8 — fast, Photon-backed suggestions biased toward your location (or the country centroid).

Validate an address format

GET /v2/validate?address=GA-142-7281

curl "https://api.afrihex.com/v2/validate?address=GA-142-7281" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

{
  "success": true,
  "data": { "valid": true, "address": "GA-142-7281", "format": "formatted" }
}

Use this to reject malformed input client-side before it reaches lookup.

Parse a free-text address

Ghanaian addresses are often relative: "Adjacent Goil Filling Station, behind Kejetia Market". POST /v2/address/parse decomposes free text into structured components plus anchors (relative-position clauses you can resolve against the landmark geocoder).

curl "https://api.afrihex.com/v2/address/parse?q=Adjacent+Goil,+Madina,+Accra" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

Nearby

Find locations around an address or coordinates within a radius:

curl "https://api.afrihex.com/v2/nearby?address=GA-142-7281&radius=2" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

curl "https://api.afrihex.com/v2/nearby?lat=5.556&lng=-0.196&radius=2" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

Reference data

• GET /v2/regions — all 16 regions with codes.
• GET /v2/districts?region=Greater%20Accra — districts by region.

Bulk operations

Process large sets in one request instead of looping:

• POST /v2/bulk/validate — validate up to 1,000 addresses.
• POST /v2/bulk/reverse — reverse-geocode up to 1,000 coordinate pairs.
• POST /v2/jobs — submit very large batches asynchronously and poll GET /v2/jobs/{id}.

Request body — both bulk endpoints take a raw JSON array (no wrapper object):

Endpoint	Body shape	Required	Definition
POST /v2/bulk/reverse	[ { "lat": …, "lng": … }, … ]	required	Up to 1,000 { lat, lng } objects
POST /v2/bulk/validate	["GA-142-7281", …]	required	Up to 1,000 address strings

curl -X POST "https://api.afrihex.com/v2/bulk/reverse" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "lat": 5.556, "lng": -0.196 },
    { "lat": 6.68, "lng": -1.62 }
  ]'

{
  "success": true,
  "data": {
    "results": [
      {
        "row": 1,
        "lat": 5.556,
        "lng": -0.196,
        "found": true,
        "gps_name": "GR0783672",
        "region": "Greater Accra",
        "district": "Korle Klottey",
        "area": "Ministries",
        "postcode": "GR078",
        "quality_score": 1
      }
    ],
    "summary": { "total": 2, "found": 2, "not_found": 0 }
  }
}

POST /v2/bulk/validate takes a JSON array of address strings instead.

Coverage

Check where the addressing grid is mapped:

• GET /v2/coverage — coverage heatmap.
• POST /v2/coverage/check — pre-flight check for a set of coordinates.

Quality score

Every resolved location includes quality_score (0.0–1.0) computed from data completeness. Banks use it to decide whether an address is verified enough for KYC — see Identity & KYC.

API reference

See Addresses & Geocoding — API Reference for every endpoint in this group.