Skip to main content

NearbyResult

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
  • ]
    • NearbyResult
    {
      "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
        }
      ]
    }