Quickstart
Quickstart
This guide takes you from zero to your first successful API call.
1. Get an API key
API access is authenticated with a key. Keys are created in the developer portal under an organization → project. The full flow (account, organization, project, key) is documented in Authentication; the short version:
Sign in to the developer portal
Authenticate to obtain a session token (POST /auth/login).
Create an organization and project
POST /developer/organizations, then POST /developer/organizations/{id}/projects.
Mint an API key
POST /developer/api-keys. The response includes the plaintext key exactly once — copy it now.
A key looks like this:
nvvo_3f9c2a1e8b7d6c5f4a3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b
2. Make your first request
Send the key in the x-api-key header. Here's a place search around Amman:
curl -s "https://navvo.io/api/v1/search?q=coffee%20in%20Abdoun" \
-H "x-api-key: nvvo_YOUR_KEY"
const res = await fetch(
"https://navvo.io/api/v1/search?" + new URLSearchParams({ q: "coffee in Abdoun" }),
{ headers: { "x-api-key": "nvvo_YOUR_KEY" } }
);
const data = await res.json();
console.log(data.places.items);
import requests
res = requests.get(
"https://navvo.io/api/v1/search",
params={"q": "coffee in Abdoun"},
headers={"x-api-key": "nvvo_YOUR_KEY"},
)
res.raise_for_status()
print(res.json()["places"]["items"])
A successful response (truncated):
{
"query": "coffee in Abdoun",
"locale": "en",
"places": {
"items": [
{
"id": "b1f3c2a0-1234-4abc-9def-0123456789ab",
"slug": "rumi-cafe-abdoun",
"nameEn": "Rumi Cafe",
"nameAr": "مقهى رومي",
"categories": ["cafe", "coffee-shop"],
"rating": 4.7,
"sponsored": true,
"center": "POINT(35.8806 31.9461)"
}
],
"total": 1,
"page": 1,
"limit": 25
}
}
POINT(<lng> <lat>) — longitude first. Coordinate conventions vary by endpoint; see Conventions.3. Add a map (optional)
Load the Navvo Maps SDK and point it straight at a Navvo style. Because browsers can't attach custom headers to map requests, pass the key as a query parameter instead:
<link href="https://docs.navvo.io/navvo-maps/navvo-maps.css" rel="stylesheet" />
<script src="https://docs.navvo.io/navvo-maps/navvo-maps.js"></script>
<div id="map" style="height: 420px;"></div>
<script>
const map = new NavvoMaps.Map({
container: "map",
style: "https://navvo.io/api/v1/tiles/style?style=standard&api_key=nvvo_YOUR_KEY",
center: [35.91, 31.95], // [lng, lat] — Amman
zoom: 12,
});
</script>
See the Display a map guide for the full walkthrough.