Developer Portal

The Developer Portal at navvo.io/developer is the fastest way to work with the Navvo API. It's a point-and-click console for everything you'd otherwise do over REST — organizations, projects, API keys, live usage, search analytics and a request sandbox.

Everything in the portal is scoped to your account: you only ever see and manage the organizations, projects and keys that you created.

Layout

The portal is organised into five tabs:

1. Set up a workspace

Open the Workspace tab and create an organization (a URL-safe slug is generated for you). Inside each organization card, add one or more projects — typically one per app or environment (for example Driver App and Rider App, or staging and production).

2. Mint an API key

Switch to the API keys tab and fill in the Create an API key form:

When you click Issue API key, the full secret is shown once in a highlighted banner. Copy it immediately — Navvo only stores a hash, so it can never be shown again.

3. Manage your keys

Each key in Your API keys shows its label, last-four, plan, status, scope count, when it was last used, and two live usage meters (requests this minute and today, against the key's quota — refreshed automatically).

A key that Navvo has made unlimited shows an Unlimited badge. Its meters still count requests this minute and today, but show them without a ceiling (1,240 / Unlimited, with no bar and no warning colour), because the key has no quota to fill.

The per-key actions are:

Lock a key to your websites or servers

In Edit, fill Allowed websites for a key used in web pages (example.com, *.example.com, localhost:3000), or Allowed IP addresses for a key used from your servers (203.0.113.7, 198.51.100.0/24). Write one entry per line. A restricted key shows Locked to … in its row. Requests from anywhere else get 403. See Authentication → Restricting a key for the matching rules.

4. Test in the sandbox

The Sandbox tab lets you fire real requests at the Navvo API and see the live response.

1. Select an API key — this is required. The dropdown lists only your own keys, so the secret never leaves the server: the portal proxies the call server-side as the key you pick.
2. Choose an endpoint from the curated, read-only list (search, geocoding, places, routing, health, …). For POST endpoints (read-only compute, e.g. routing) you can edit the JSON body. The sandbox deliberately exposes only safe, non-mutating endpoints.
3. Send request — the button is disabled until you've selected a key.

The response panel shows the HTTP status, round-trip time, and the formatted JSON body. The sandbox applies your key's scope and active-state checks before forwarding: if the selected key is inactive, or is missing a scope the endpoint needs, you'll get a 403 explaining exactly what's wrong — a quick way to verify a key is configured correctly before you ship. It does not apply the key's website or IP restrictions, because the request runs on Navvo's servers on your behalf.

5. Watch your search analytics

The Search analytics tab shows the searches made with one project's API keys. Only a project's owner can see its analytics; for a legacy project with no owner, only Navvo's highest admin role (super_admin) can. Pick a project and a range of 7, 30 or 90 days (days follow Asia/Amman time):

• Six tiles: searches, zero-result rate, click-through rate, average click position, conversion rate and median response time. A rate backed by fewer than 30 searches shows Insufficient data rather than a misleading number.
• Searches per day, as a chart or a table.
• Top queries and Queries with no results, 20 of each, with searches, zero-result rate, click-through rate, conversions and when each was last seen. The no-results list is the quickest way to find the places and spellings your users expect and don't get.

Click-through and conversion rates stay empty until your app reports what users opened, with search events sent for searches that carried a user-consented session id.

Choose how long Navvo keeps your searches

Moving from 90 to 30 days deletes the older searches at the next nightly clean-up. Deleted data can't be restored, so the portal asks you to confirm first. Search analytics & privacy lists what a search record holds and what is never stored. In short: the query text after emails, phone numbers and other personal details are removed, the filters and results, and a coarse area instead of coordinates. Search records never contain the IP address itself. Separately, and whatever this setting, usage metering records the address each API-key call comes from (usually your server; your user's device when a key is used from a browser or an app) for billing and abuse prevention. A single request can stay out of analytics with analytics=false.

Over the API

These endpoints take the same bearer token as the rest of the portal and follow the same access rule as the tab:

curl "https://navvo.io/api/v1/developer/projects/PROJECT_ID/search-analytics?days=30" \
  -H "Authorization: Bearer $NAVVO_TOKEN"

curl -X PATCH "https://navvo.io/api/v1/developer/projects/PROJECT_ID/search-settings" \
  -H "Authorization: Bearer $NAVVO_TOKEN" -H "Content-Type: application/json" \
  -d '{"analytics":"90"}'

GET …/search-analytics takes days = 7, 30 or 90 (default 30) and returns:

{
  "project": { "id": "…", "name": "Rider App", "slug": "rider-app", "organization": { "id": "…", "name": "Acme Mobility", "slug": "acme-mobility" } },
  "range": { "days": 30, "from": "2026-09-01", "to": "2026-09-30", "timeZone": "Asia/Amman" },
  "settings": { "analytics": "30", "retentionDays": 30, "isDefault": true },
  "available": true,
  "overview": {
    "searches": 1240, "requests": 1512, "sessions": 0,
    "zeroRate": 0.06, "ctr": null, "avgClickPos": null, "conversionRate": null,
    "p50Ms": 38, "p95Ms": 190, "hybridShare": 0,
    "insufficient": { "zeroRate": false, "ctr": true, "avgClickPos": true, "conversionRate": true },
    "series": [{ "day": "2026-09-30", "searches": 52, "zero": 3, "clicks": 0, "conversions": 0 }]
  },
  "topQueries": {
    "total": 318,
    "items": [{ "query": "pharmacy", "qNorm": "pharmacy", "searches": 96, "sessions": 0, "zeroRate": 0, "ctr": null, "avgClickPos": null, "conversions": 0, "lastSeen": "2026-09-30T11:02:11.000Z" }]
  },
  "zeroResultQueries": { "total": 21, "items": [] }
}

• Rates are fractions (0.06 = 6%). null means there was nothing to divide by.
• searches leaves out keystrokes that the same user replaced with a longer query within 10 seconds; requests counts every call.
• hybridShare is the share of searches where meaning-based matching contributed.
• available: false means analytics are temporarily unavailable. The numbers are then empty, not zero.
• With analytics: "off", overview is null and both lists are empty.

PATCH …/search-settings takes {"analytics": "off" | "30" | "90"} and returns the project with its new settings.

Deleting one end user's searches. If one of your users asks you to delete their data, call DELETE …/search-sessions/SESSION_ID with the session id your app sent for them in X-Navvo-Session:

curl -X DELETE "https://navvo.io/api/v1/developer/projects/PROJECT_ID/search-sessions/SESSION_ID" \
  -H "Authorization: Bearer $NAVVO_TOKEN"

It removes that session's searches and click events from the last 91 days and returns how many were deleted: {"project": {…}, "deleted": {"queries": 12, "events": 3}}. Navvo stores only a daily hash of a session id, so the id itself has to come from you; searches sent without a session id can't be tied to a user and aren't affected. Only the project's owner can call it, and each call is recorded in the audit log without the id. A malformed id answers 400.

Prefer the API?

Everything in the portal is backed by the /developer/* REST endpoints documented in Authentication → Managing keys, so you can script organization, project and key management into your own tooling.