Search events

Tell Navvo which search result a user opened (a click) and what they did with it next (a conversion, such as asking for directions, calling or saving). Navvo uses events to measure search quality: how often people open a result, how far down the list they click, and which searches lead nowhere. It uses them to find ranking problems too. Events are optional, and search works the same without them.

Events are consent-gated. Navvo accepts them only for searches made with an X-Navvo-Session header, which you send only after the user agrees. Search analytics & privacy explains the whole model.

Authentication: the same API key that ran the search. Event calls are not metered.

POST /search/events

curl -s -X POST "https://navvo.io/api/v1/search/events" \
  -H "x-api-key: nvvo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "queryId": "AaDxmIYgiEC1I4ZdHCWiERmR", "type": "click", "name": "open_place",
        "placeId": "e3bacbd9-1e5d-474c-b84e-2fe7e1556541", "position": 1 },
      { "queryId": "AaDxmIYgiEC1I4ZdHCWiERmR", "type": "conversion", "name": "directions",
        "placeId": "e3bacbd9-1e5d-474c-b84e-2fe7e1556541" }
    ]
  }'

Which searches accept events

An event is accepted only when the search it points to was event-eligible:

1. The GET /search request carried an X-Navvo-Session header, sent because the user consented.
2. That request carried neither Sec-GPC: 1 nor DNT: 1.
3. Neither the query nor its top result was in a sensitive category (health or religion). Navvo never links those searches to a session.
4. You send the event within 7 days of the search, with the same API key the search used.

The search response doesn't say whether it was eligible, and you don't need to know. Send events for the searches where you sent a session id. Ineligible ones come back counted in rejected, and nothing else is affected.

Request body

Each events[] element:

You can send a conversion without a click first, for example from a "Directions" button on the result row. Arrival events are not supported.

Response (202)

{ "accepted": 1, "rejected": 1, "reasons": { "not_eligible": 1 } }

How events are used

• Navvo joins each event to its search by queryId. A click counts toward search metrics only when the place was among the first 20 results that search returned.
• Clicks on promoted or sponsored results are never used to learn ranking.
• Events are kept for 90 days, and events whose search record never arrived are deleted after about 24 hours. If a project switches its search analytics off, Navvo stops accepting events for the project's keys within about a minute and deletes the events already stored. Search analytics & privacy lists what Navvo keeps and for how long.

Sending events from an app or browser

// Call when the user opens a result. `search` is the GET /search response the result came from.
function reportClick(search, place, index) {
  const position = (search.places.page - 1) * search.places.limit + index + 1;
  return fetch("https://navvo.io/api/v1/search/events", {
    method: "POST",
    keepalive: true, // survives the page navigating away
    headers: { "Content-Type": "application/json", "x-api-key": KEY },
    body: JSON.stringify({
      events: [{ queryId: search.queryId, type: "click", name: "open_place", placeId: place.id, position }],
    }),
  }).catch(() => {}); // analytics must never break your UI
}

• Use fetch with keepalive: true. navigator.sendBeacon can't send the x-api-key header.
• If your backend proxies search to keep your key secret, proxy events the same way, because an event must carry the key the search used.
• A browser request without an API key is accepted only from Navvo's own sites. Third-party pages must send their key.
• Don't send events for a search response that was served from a cache. Search responses carry Cache-Control: no-store for this reason.
• If you collect several events (for example, when the page is hidden), send up to 20 in one request.

With the Navvo SDKs

The Web SDK (@navvo/maps-js 0.2) and the Node SDK (@navvo/sdk 0.2) send events for you with the key the search used, and the Web SDK uses keepalive:

// Browser: @navvo/maps-js
import { NavvoServices, createSearchSessionId } from "@navvo/maps-js";
const services = new NavvoServices({ apiKey: KEY });
const session = createSearchSessionId(); // only if your user agreed to it
const r = await services.search("rumi cafe", { session });
const hit = r.items[0];
await services.sendSearchEvent({ queryId: r.queryId!, type: "click", placeId: hit.id, position: hit.position });

// Server: @navvo/sdk
const res = await navvo.search("rumi cafe", { session });
await navvo.sendSearchEvent({ queryId: res.queryId!, type: "conversion", name: "directions", placeId, position });

In the Web SDK every result carries its 1-based position, page offset included. See the Node.js SDK guide for the server side.

Errors