Addressing

Across much of the MENA region, formal street addresses are sparse, informal, or simply not signed — a building may be known only as "the third turn after the bakery." Navvo's Addressing layer fixes this with Plus Codes: a short, globally-unique code derived directly from a coordinate. Any point on Earth gets a compact address that is offline-derivable (no lookup needed to compute it), globally unique, and shareable — paste it into a message and the recipient lands within metres. Codes can be shortened to a local form (relative to a nearby locality) for everyday use, e.g. XW36+H6 Abdoun, Amman.

This page covers encoding a point to a code, decoding a code back to a coordinate, the full addressing bundle for a point, and a fault-tolerant geocoding autocomplete tuned for Arabic input.

GET /geo/pluscode

Encode a coordinate into a Plus Code (Open Location Code).

Scope required: geo

Query parameters

curl -s "https://navvo.io/api/v1/geo/pluscode?lat=31.94920&lng=35.89970&length=10" \
  -H "x-api-key: nvvo_YOUR_KEY"

Response

{
  "provider": "navvo-addressing",
  "code": "8G3QXW36+H6",
  "lat": 31.9492,
  "lng": 35.8997
}

Errors

GET /geo/pluscode/decode

Decode a Plus Code back into a coordinate and its bounding cell. Accepts either a full code or a short/local code; for a short code, supply a reference lat/lng so the nearest matching cell can be recovered.

Scope required: geo

Query parameters

# Full code — no reference needed
curl -s "https://navvo.io/api/v1/geo/pluscode/decode?code=8G3QXW36%2BH6" \
  -H "x-api-key: nvvo_YOUR_KEY"

# Short/local code — supply a nearby reference point
curl -s "https://navvo.io/api/v1/geo/pluscode/decode?code=XW36%2BH6&lat=31.95&lng=35.90" \
  -H "x-api-key: nvvo_YOUR_KEY"

Response

{
  "provider": "navvo-addressing",
  "code": "8G3QXW36+H6",
  "lat": 31.949125,
  "lng": 35.899625,
  "bounds": {
    "south": 31.94906,
    "west": 35.89956,
    "north": 31.94919,
    "east": 35.89969
  }
}

Errors

GET /geo/address

Resolve a coordinate to the full addressing bundle — everything a client needs to display and share a human-friendly address for a point. This is the recommended endpoint for MENA addressing: it combines the global code, the local code, the locality name, a ready-to-render localAddress, and a shareable URL in one call.

Scope required: geo

Query parameters

curl -s "https://navvo.io/api/v1/geo/address?lat=31.94920&lng=35.89970" \
  -H "x-api-key: nvvo_YOUR_KEY"

Response

{
  "provider": "navvo-addressing",
  "lat": 31.9492,
  "lng": 35.8997,
  "plusCode": "8G3QXW36+H6",
  "shortCode": "XW36+H6",
  "locality": "Abdoun, Amman",
  "localAddress": "XW36+H6 Abdoun, Amman",
  "shareUrl": "https://navvo.io/a/8G3QXW36+H6"
}

Errors

POST /geo/address/batch

Bulk addressing — resolve up to 50 coordinates to Plus Code addresses in one request (the batch form of GET /geo/address). Each point returns the full bundle (plusCode, shortCode, locality, localAddress). Scope required: geo.

curl -s -X POST "https://navvo.io/api/v1/geo/address/batch" \
  -H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
  -d '{ "points": [ {"lat":31.9539,"lng":35.9106}, {"lat":29.532,"lng":35.006} ], "length": 10 }'

{
  "provider": "navvo-addressing", "count": 2, "resolved": 2,
  "results": [
    { "lat": 31.9539, "lng": 35.9106, "ok": true, "plusCode": "8G3QXW36+H6", "shortCode": "XW36+H6", "locality": "منطقة زهران, عمان", "localAddress": "XW36+H6 منطقة زهران, عمان" }
  ]
}

resolved counts the successful points; a point with out-of-range or non-numeric coordinates returns ok:false with error: "invalid coordinates". 400 if points[] is missing/empty.

GET /geocode/autocomplete

Fault-tolerant typeahead suggestions for an in-progress query. Built for messy real-world MENA input: it applies Arabic normalization (tolerating common letter variants such as أ/إ/آ → ا, ة → ه, and stripping diacritics) and understands Arabizi — the Latin "chat alphabet" with numbers standing in for Arabic letters (e.g. shar3 abdali → شارع العبدلي). It is designed to return relevant results even when the query is partial or loosely spelled.

Scope required: geocode

Query parameters

# Arabizi input — chat-alphabet with a digit standing in for an Arabic letter
curl -s "https://navvo.io/api/v1/geocode/autocomplete?q=shar3%20abdali&limit=5" \
  -H "x-api-key: nvvo_YOUR_KEY"

Response

{
  "provider": "navvo-geocode",
  "query": "shar3 abdali",
  "normalizedQuery": "شارع العبدلي",
  "suggestions": [
    {
      "id": "way/98765432",
      "label": "شارع العبدلي، عمّان",
      "name": "شارع العبدلي",
      "lat": 31.96374,
      "lng": 35.92213,
      "type": "road",
      "category": "highway"
    }
  ]
}

Errors