GuidesAPI Reference
Guides
  1. HERE Geocoding and Search API v7 Developer Guide
  2. HERE Geocoding and Search API v7 endpoints

Signals

The /signals endpoint enables developers to contribute to the continuous improvement of HERE Geocoding and Search response quality by sharing end-user interactions with API response items returned by any endpoint.

Currently, the endpoints that benefit most from end-user feedback are:

  • the /discover endpoint
  • the /autosuggest endpoint

Requests

The /signals endpoint call shares information about an action performed by a user at a specific time on an item at a given rank within a search response.

Each request to the /signals endpoint must include the following fields:

  • action: The action performed by the user.
  • timestamp: The time the action occurred.
  • correlationId: The identifier of the API response acted upon.
  • resourceId: The identifier of the specific item acted upon.
  • rank: The item's position in the response.

Request Format

A /signals endpoint call is an HTTP 1.1 POST request to the following base URL:

https://signals.search.hereapi.com

The request body must use the x-www-form-urlencoded format:

version=1&timetamp=<timestamp>&resourceId=<resourceId>&correlationId=<correlationId>&rank=<rank>&action=<action>

Example:

version=1&timestamp=1675403788324&resourceId=here:pds:place:250u09tu-4561b8da952f4fd79c4e1998c3fcf032&correlationId=22457435-efcf-46b9-8c87-62912f3f2f0&rank=0&action=here:gs:action:navigate-to

Field Details

version

Each /signals call body must contain a version field. Currently, only version=1 is supported.

action

Every request to the /signals endpoint must include an action field.

The supported actions are:

actionTo be sent when the end-user ...
here:gs:action:calluses the result's phone number
here:gs:action:emailuses the result's email address
here:gs:action:navigate-tostarts a navigation to the result item
here:gs:action:navigate-fromstarts a navigation from the result item
here:gs:action:pinbookmarks a result or adds it to a collection
here:gs:action:taptaps on the result displayed on a map
here:gs:action:viewselects a result in a list
here:gs:action:shareshares/sends a result to another user or as a mail/PM
here:gs:action:visitvisits the result's website
📘

Note:

Applications offering navigation between two search results must send two signals:

  • One for the destination (here:gs:action:navigate-to)
  • One for the starting location (here:gs:action:navigate-from)
  • A navigate-from signal is not required if the starting position is the user’s current location or does not originate from a HERE Geocoding and Search API search result.

correlationId and resourceId

Each API response includes a header: X-Correlation-ID. Use this value for the correlationId field.

Each response item includes an id field. Use this value for the resourceId field.

timestamp

The timestamp field must be the Unix Epoch time in milliseconds when the user performed the action.

rank

The rank field represents the index of the item within the items array of the response.

  • The first item has index 0.
  • For /lookup responses (which contain a single item and no items array), set rank=0.
📘

Note

The /signals endpoint is released as RESTRICTED. See the privilege section in the feature maturity topic for more information.

For more information, see the API reference.

Updated last month