Signals

The HERE Search Signals endpoint lets the client report user actions on search results back to the backend. This page explains what it is for and how the client handles it. For the step-by-step call, see the Report a user action guide; for the method signature, see the API Reference.

Purpose

Reporting interactions (viewing, selecting, or otherwise acting on a result) gives HERE feedback that can be used for analytics, personalization, and improving search relevance.

Typical actions include:

  • viewing a result;

  • selecting a result as start / end / stop;

  • other custom actions (e.g. here:gs:action:view, start, end).

What is sent

Each signal carries:

Field

Meaning

resourceId

The HERE result id the action was performed on

correlationId

The X-Correlation-ID from the response that produced the result

rank

The position of the result in its result list

action

The action performed (e.g. here:gs:action:view)

version

Signals protocol version (currently 1)

(optional)

Additional body fields such as userId, asSessionId

From an end-user perspective this is transparent and does not affect the experience. No personal data is sent unless the developer explicitly configures it (e.g. by passing userId or an X-User-ID header).

How the client handles it

API.signals (src/here_search_demo/api.py):

  • builds a form-encoded POST body from the fields above (plus any extra keyword arguments);

  • sends it to the /v1/signals endpoint;

  • returns None on failure instead of raising, so a failed signal never interrupts the search flow;

  • logs the action when logging is enabled, which is the easiest way to confirm signals are being emitted.

Because signals are fire-and-forget and non-blocking, they are safe to emit from UI event handlers without guarding the surrounding interaction.

See also