Report a user action (Signals)

This guide shows how to report a user interaction on a search result via the HERE Search Signals endpoint. For what signals are and why they exist, see the Signals explanation; for the full method signature, see the API Reference.

Steps

Call the async API.signals method with the result you want to report:

await api.signals(
    session,                        # HTTPSession instance
    resource_id="here:poi:1234",    # HERE result id
    correlation_id="abcd-efgh-5678",# X-Correlation-ID from the response that produced it
    rank=2,                         # result position in its list
    action="here:gs:action:view",  # action performed
)

The four required arguments are resource_id, correlation_id, rank, and action. version=1 is added for you.

Attach optional fields

Extra body fields (for example userId or asSessionId) are passed as keyword arguments and forwarded into the POST body. Custom X-* headers go through x_headers:

await api.signals(
    session,
    resource_id="here:poi:1234",
    correlation_id="abcd-efgh-5678",
    rank=2,
    action="here:gs:action:view",
    userId="user-42",                       # extra body field
    x_headers={"X-User-ID": "user-42"},     # extra header
)

Verify it worked

• API.signals returns a Response on success and None on failure — it never raises, so it is safe to call from a UI event handler.

• If you get None, confirm all four required fields are set and correct.

• Enable logging to see the emitted signal in the log output.