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,
    "quality_tier": "high",
    "provenance": {
      "source": "third_party_match",
      "provider": "ghanapostgps",
      "confidence": 0.95
    }
  }
}

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

quality_tier is a threshold-free read of quality_score (high ≥ 0.8, medium ≥ 0.5, else low). provenance is a separate axis — how the coordinate was established, not how complete the record is — see Quickstart for how to use both together. For /v2/lookup and /v2/reverse specifically, provenance.source is always third_party_match, since both are matched against a single registry (GhanaPostGPS) rather than confirmed on the ground.

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"

{
  "success": true,
  "data": {
    "gps_name": "GR0783672",
    "address": "GR0783672",
    "region": "Greater Accra",
    "district": "Korle Klottey",
    "area": "Ministries",
    "postcode": "GR078",
    "street": "Egypt Lane",
    "center_latitude": 5.55598867225891,
    "center_longitude": -0.1959899371083825,
    "google_maps_url": "https://www.google.com/maps/search/?api=1&query=5.555989,-0.195990",
    "quality_score": 1,
    "quality_tier": "high",
    "provenance": {
      "source": "third_party_match",
      "provider": "ghanapostgps",
      "confidence": 0.95
    }
  }
}

Coordinates outside the active country's bounds return 400 OUT_OF_BOUNDS. See Resolve a GPS code above for what quality_tier and provenance mean.

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"

{
  "success": true,
  "data": {
    "query": "Adjacent Goil Filling Station, Madina, Accra",
    "is_code": false,
    "parsed": {
      "house": "madina accra",
      "anchors": [
        { "relation": "adjacent", "name": "goil filling station" }
      ],
      "geocode_query": "madina accra"
    }
  }
}

Resolve each anchor.name via the landmark geocoder to pin the exact spot.

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"

{
  "success": true,
  "data": {
    "origin": {
      "gps_name": "GR0783672",
      "address": "GR0783672",
      "region": "Greater Accra",
      "district": "Korle Klottey",
      "area": "Ministries",
      "postcode": "GR078",
      "street": "Egypt Lane",
      "center_latitude": 5.55598867225891,
      "center_longitude": -0.1959899371083825,
      "quality_score": 1
    },
    "radius_km": 2,
    "count": 2,
    "has_more": false,
    "locations": [
      {
        "location": {
          "gps_name": "GR0785674",
          "address": "GR0785674",
          "region": "Greater Accra",
          "district": "Korle Klottey",
          "area": "Ministries",
          "postcode": "GR078",
          "center_latitude": 5.5564,
          "center_longitude": -0.1952,
          "quality_score": 1
        },
        "distance_km": 0.14
      }
    ]
  }
}

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.

Resolve a GPS code to coordinates​

Reverse geocode coordinates​

Search by place name​

Validate an address format​

Parse a free-text address​

Nearby​

Reference data​

Bulk operations​

Coverage​

Quality score​

API reference​