Skip to main content

NearbyResponse

successboolean
Example: true
data object
origin 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>
radius_kmnumber<double>

Search radius in kilometers

Example: 1
countinteger

Number of nearby locations in this page

Example: 10
has_moreboolean

Whether there are more results beyond this page

Example: true
next_cursorstring

Pass this as the cursor query param to get the next page (distance_km value)

Example: 0.523000
locations object[]
  • Array [
    • location 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>
    distance_kmnumber<double>

    Distance from origin in kilometers

    Example: 0.23
  • ]
    • 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
    NearbyResponse
    {
      "success": true,
      "data": {
        "origin": {
          "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"
          }
        },
        "radius_km": 1,
        "count": 10,
        "has_more": true,
        "next_cursor": "0.523000",
        "locations": [
          {
            "location": {
              "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"
              }
            },
            "distance_km": 0.23
          }
        ]
      },
      "meta": {
        "request_id": "c86825f0-d8ca-4ae1-8226-514cc48e05c0",
        "cached": false,
        "latency": "1.802457582s",
        "boundary_distance_m": 1.42,
        "near_grid_boundary": false
      }
    }