API Reference

Geocoding

Forward and reverse geocoding powered by Navvo's map data.

Geocoding

Convert free-text addresses to coordinates (forward) and coordinates to addresses (reverse). Geocoding is a normalizing layer over Navvo's geocoding engine.

Scope required: geocode

Both endpoints return a { provider, available, data }envelope. When the geocoder is unreachable you still get a 200 with available: false and a status field — always check available before reading data.

GET /geocode/search

Forward geocoding — resolve a query string to candidate places.

curl -s "https://navvo.io/api/v1/geocode/search?q=Abdali%20Hospital%2C%20Amman&limit=5" \
  -H "x-api-key: nvvo_YOUR_KEY"

Query parameters

string required

Free-text query, e.g. Abdali Hospital, Amman. Must be non-empty.

locale

string

Language preference. Defaults to ar,en (Arabic-first). Used as the accept-language hint.

limit

string

Max results. Defaults to 20, hard-capped at 50.

lat

string

Latitude for proximity bias (applied only when paired with lon).

lon

string

Longitude for proximity bias (paired with lat).

bbox

string

Viewbox bias as west,south,east,north (longitude first).

Response

The envelope: provider ("navvo"), available (boolean), and data — an array of results, each with the shape below.

{
  "provider": "navvo",
  "available": true,
  "data": [
    {
      "place_id": 12345678,
      "osm_type": "way",
      "osm_id": 98765432,
      "lat": "31.9637400",
      "lon": "35.9221300",
      "category": "amenity",
      "type": "hospital",
      "name": "Abdali Hospital",
      "display_name": "Abdali Hospital, Al Abdali, Amman, Jordan",
      "address": { "suburb": "Al Abdali", "city": "Amman", "country": "Jordan", "country_code": "jo" },
      "boundingbox": ["31.963", "31.964", "35.921", "35.923"]
    }
  ]
}

When the geocoder fails or is not configured:

{ "provider": "navvo", "available": false, "status": 502 }

lat/lon come back as strings. Parse them before using as numbers.

Errors

Status	When
`400`	`q` missing/blank, or `limit`/`lat`/`lon` not numeric.
`401` / `403`	Missing/invalid key, or key lacks the `geocode` scope.

Geocoder failures surface as available: false inside a 200, never as a 5xx.

GET /geocode/autocomplete

Lightweight typeahead — the endpoint to call on every keystroke of a search box. It applies the same Arabic/Arabizi-aware matching as /geocode/search but returns a trimmed, ready-to-render payload (id, label, numeric coordinates). Prefer this over polling /geocode/search for suggestions: smaller responses, numeric lat/lng, and a sensible default limit.

curl -s "https://navvo.io/api/v1/geocode/autocomplete?q=abdali&limit=8" \
  -H "x-api-key: $NAVVO_API_KEY"

Query parameters

Same as /geocode/search (q required; optional locale, lat/lon proximity bias, bbox), except limit defaults to 8 and is capped at 15.

Response

{
  "provider": "navvo-geocode",
  "query": "abdali",
  "suggestions": [
    {
      "id": "131530",
      "label": "العبدلي, منطقة زهران, عمان, الأردن",
      "name": "العبدلي",
      "lat": 31.9593159,
      "lng": 35.9187494,
      "type": "neighbourhood",
      "category": "place"
    }
  ]
}

Field	Type	Notes
`suggestions[].id`	string	stable candidate id
`suggestions[].label`	string	full display line for the dropdown row
`suggestions[].name`	string	short primary name
`suggestions[].lat` / `lng`	number \| null	numeric coordinates (unlike `/geocode/search`, no string parsing needed)
`normalizedQuery`	string	present when the query was normalized (Arabic variants / Arabizi) before matching

GET /geocode/reverse

Reverse geocoding — resolve a coordinate to the nearest address. Always resolves at street/building detail (zoom=18).

curl -s "https://navvo.io/api/v1/geocode/reverse?lat=31.95&lon=35.91" \
  -H "x-api-key: nvvo_YOUR_KEY"

Query parameters

lat

string required

Latitude in decimal degrees.

lon

string required

Longitude in decimal degrees.

locale

string

Address language — ar, en, or a preference list like ar,en (the default). Controls the language of display_name and the address parts, same convention as forward geocoding.

Response

The envelope data is a single object (the geocoder's raw reverse result):

{
  "provider": "navvo",
  "available": true,
  "data": {
    "place_id": 12345678,
    "osm_type": "way",
    "lat": "31.95",
    "lon": "35.91",
    "category": "highway",
    "type": "residential",
    "name": "King Hussein Street",
    "display_name": "King Hussein Street, Al Abdali, Amman, Jordan",
    "address": { "road": "King Hussein Street", "suburb": "Al Abdali", "city": "Amman", "country": "Jordan", "country_code": "jo" }
  }
}

Errors

Status	When
`400`	`lat` or `lon` missing / not numeric.
`401` / `403`	Missing/invalid key, or key lacks the `geocode` scope.

POST /geocode/batch

Bulk forward geocoding — resolve many addresses in a single request (CSV imports, dataset enrichment). Returns the top match per query. Up to 50 queries per call; the same Arabic-/Arabizi-aware matching as /geocode/search applies to each.

curl -s -X POST "https://navvo.io/api/v1/geocode/batch" \
  -H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
  -d '{ "queries": ["Amman", "Aqaba", "Irbid"], "locale": "ar" }'

Field	Type	Notes
`queries`	string	required — addresses/places to geocode (max 50)
`locale`	string	optional result language hint
`bbox`	string	optional `minLng,minLat,maxLng,maxLat` to bias results

{
  "provider": "navvo-geocode", "count": 3, "found": 3,
  "results": [
    { "query": "Amman", "found": true, "lat": 31.9539, "lng": 35.9106, "displayName": "عمان, الأردن", "type": "city", "category": "place" },
    { "query": "Aqaba", "found": true, "lat": 29.58, "lng": 35.289, "displayName": "العقبة, الأردن", "type": "city", "category": "place" }
  ]
}

Field	Type	Notes
`count`	number	queries processed
`found`	number	how many resolved to coordinates
`results[]`	array	`{ query, found, lat, lng, displayName, type, category }` — `found:false` (with null coords) when a query has no match

Queries run with limited concurrency to respect upstream rate limits; expect a few hundred ms per ~4 addresses.

Errors

Status	When
`400`	`queries[]` missing or empty.
`401` / `403`	Missing/invalid key, or key lacks the `geocode` scope.

POST /geocode/reverse-batch

Bulk reverse geocoding — turn many coordinates into addresses in one request (the inverse of /geocode/batch). Top match per point; up to 50 points per call.

curl -s -X POST "https://navvo.io/api/v1/geocode/reverse-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} ] }'

Field	Type	Notes
`points`	array	required — `{ lat, lng }` (or `lon`) objects, max 50
`locale`	string	optional address language — `ar`, `en`, or `ar,en` (default), applied to every point

{
  "provider": "navvo-geocode", "count": 2, "found": 2,
  "results": [
    { "lat": 31.9539, "lng": 35.9106, "found": true, "displayName": "الدوار الثالث, منطقة زهران, عمان, الأردن", "type": "…", "address": { } }
  ]
}

A point with no match (or invalid coordinates) returns found: false.

Errors

Status	When
`400`	`points[]` missing or empty.
`401` / `403`	Missing/invalid key, or key lacks the `geocode` scope.

Addressing configuration.GET /geo/addressing/config returns the platform's addressing settings — whether short location codes are enabled (plusCodesEnabled, defaultCodeLength), the share URL base, and national-address integration status — so clients can decide which address formats to render. See Addressing for the full addressing API.

Route Optimization

Self-hosted OR-Tools route optimization — VRP/VRPTW with capacity, time windows, pickup-delivery and multi-depot, plus bin-packing, driver rostering, live re-optimization, and async optimization-as-a-job.

Quests (crowd data)

Gamified, crowd-sourced data improvement — surface nearby data-gap micro-tasks, collect answers into the moderation queue, and award contributor points.