Skip to main content

LocationResponse

successboolean
Example: true
data object
gps_namestring

Canonical GhanaPostGPS name

Example: AKW4849321
addressstring

Address identifier

Example: AKW4849321
regionstring

Region name

Example: Ashanti
districtstring

District name

Example: Kwadaso
areastring

Area/neighborhood name

Example: Hemang
postcodestring

Postal code

Example: AKW484
streetstring

Street name (if known)

center_latitudenumber<double>

Center latitude of the address area

Example: 6.650080145273592
center_longitudenumber<double>

Center longitude of the address area

Example: -1.648700346667856
north_latitudenumber<double>

North boundary latitude

south_latitudenumber<double>

South boundary latitude

east_longitudenumber<double>

East boundary longitude

west_longitudenumber<double>

West boundary longitude

google_maps_urlstring

Direct link to view the location on Google Maps

Example: https://www.google.com/maps/search/?api=1&query=6.650080,-1.648700
quality_scorenumber<double>

Address confidence score (0.0–1.0) based on data completeness. Useful for KYC and address verification.

Scoring breakdown:

  • GPS name (0.15), Region (0.10), District (0.10), Postcode (0.10), Coordinates (0.15) = 0.60 base
  • Area (0.10), Street (0.10), Bounding box (0.10), Maps URL (0.10) = 0.40 enrichment

A fully mapped address scores 1.0. Use a threshold (e.g. 0.7) to filter verified addresses.

Possible values: >= 0 and <= 1

Example: 0.85
confidencestring

Human-readable tier derived from quality_score: high (>= 0.8), medium (>= 0.5), low (< 0.5). A quick filter when you don't want to pick your own quality_score threshold.

Possible values: [high, medium, low]

Example: high
provenance object

quality_score/confidence above measure data completeness, not independent ground-truth verification — every /v2/lookup and /v2/reverse result comes from a single source (matched against GhanaPostGPS's own registry), so provenance.source is always third_party_match here. Don't mistake a high quality_score for a customer- or agent-confirmed point — see /v2/address/resolve's provenance for the tiers that distinguish those.

sourcestring

device_gps: a live GPS/network/fused fix reported by a device at request time. geocoded_text: inferred purely from parsing/matching text or grid math, no real-world confirmation. third_party_match: matched against an external dataset (OSM, Google Open Buildings, GhanaPostGPS's own registry) without independent confirmation on the ground. user_confirmed: explicitly entered/confirmed by the address owner. agent_verified: independently confirmed by a human or a real event — a field agent's manual promotion, a signed proof-of-delivery — the strongest tier.

Possible values: [device_gps, geocoded_text, third_party_match, user_confirmed, agent_verified]

Example: agent_verified
providerstring

The upstream/system that produced the point (e.g. "ghanapostgps", "osm", "google_open_buildings", "customer_app"), separate from source's trust tier.

Example: ghanapostgps
accuracy_metersnumber<double>

A physical measurement (GPS accuracy, computed drift, snap distance) — independent of confidence.

confidencenumber<double>

Trust score, 0.0–1.0.

Possible values: >= 0 and <= 1

Example: 0.85
verified_atstring<date-time>
meta object
request_idstring<uuid>

Unique request identifier

Example: c86825f0-d8ca-4ae1-8226-514cc48e05c0
cachedboolean

Whether the response was served from cache

Example: false
latencystring

Server-side processing time

Example: 1.802457582s
boundary_distance_mnumber<double>nullable

Reverse-geocode responses only. Distance in metres from the queried coordinate to the nearest edge of the resolved GhanaPostGPS grid cell. Omitted when the upstream response carried no cell bounds.

Example: 1.42
near_grid_boundaryboolean

Reverse-geocode responses only. True when boundary_distance_m is small enough that an ordinary GPS fix's jitter could plausibly have resolved to the neighbouring cell's code instead — the documented cause of the same property getting different GhanaPostGPS codes depending on where you stand.

Example: false
LocationResponse
{
  "success": true,
  "data": {
    "gps_name": "AKW4849321",
    "address": "AKW4849321",
    "region": "Ashanti",
    "district": "Kwadaso",
    "area": "Hemang",
    "postcode": "AKW484",
    "street": "string",
    "center_latitude": 6.650080145273592,
    "center_longitude": -1.648700346667856,
    "north_latitude": 0,
    "south_latitude": 0,
    "east_longitude": 0,
    "west_longitude": 0,
    "google_maps_url": "https://www.google.com/maps/search/?api=1&query=6.650080,-1.648700",
    "quality_score": 0.85,
    "confidence": "high",
    "provenance": {
      "source": "agent_verified",
      "provider": "ghanapostgps",
      "accuracy_meters": 0,
      "confidence": 0.85,
      "verified_at": "2024-07-29T15:51:28.071Z"
    }
  },
  "meta": {
    "request_id": "c86825f0-d8ca-4ae1-8226-514cc48e05c0",
    "cached": false,
    "latency": "1.802457582s",
    "boundary_distance_m": 1.42,
    "near_grid_boundary": false
  }
}