Guides
Address autocomplete & geocoding
Turn user-typed addresses into coordinates, and coordinates into addresses.
Address autocomplete & geocoding
Resolve free-text addresses to coordinates (forward geocoding) and coordinates back to addresses (reverse geocoding). Uses Geocoding.
Scope required: geocode
Forward: address → coordinates
Call GET /geocode/search as the user types (debounced). Bias results toward the visible map with bbox, or toward a point with lat/lon:
async function geocode(q, viewport) {
const params = new URLSearchParams({ q, limit: "5" });
if (viewport) params.set("bbox", viewport.join(",")); // west,south,east,north
const res = await fetch("https://navvo.io/api/v1/geocode/search?" + params, {
headers: { "x-api-key": KEY },
});
const out = await res.json();
if (!out.available) return []; // geocoder offline
return out.data; // array of candidates
}
Each item from Navvo's geocoding engine has
display_name, lat, lon (strings), type, and address. See the Geocoding reference.Render display_name in your dropdown and use lat/lon when the user picks one:
const items = await geocode("Abdali Boulevard, Amman", [35.85, 31.90, 35.99, 31.99]);
items.forEach((it) => {
console.log(it.display_name, "→", Number(it.lon), Number(it.lat)); // [lng, lat]
});
Reverse: coordinates → address
When the user drops a pin or you have a GPS fix, call GET /geocode/reverse:
async function reverse(lat, lon) {
const res = await fetch(
"https://navvo.io/api/v1/geocode/reverse?" + new URLSearchParams({ lat, lon }),
{ headers: { "x-api-key": KEY } }
);
const out = await res.json();
return out.available ? out.data : null; // single result object
}
const place = await reverse(31.95, 35.91);
console.log(place.display_name); // "King Hussein Street, Al Abdali, Amman, Jordan"
Tips
Debounce input
Only call the API after the user pauses (~250–300ms). Geocoding counts against your rate limit like any other request.
Bias to the viewport
Pass the map's
bbox (or a lat/lon proximity point) so the most relevant local results rank first.Parse string coordinates
lat/lon come back as strings. Wrap with Number(...) before using them as map coordinates.