Action on Autosuggest response

The application described in the parent page provides a one-box search form that allows end-users to enter queries in text form. To support this, the application uses the /autosuggest endpoint to retrieve suggestions as the user types.

Example: Autosuggest Query

For instance, when an end-user searching for restaurants at position (52.5044,13.33673) enters the letters sequence "r", "e", "s", "t" in the one-box form, the application sends a sequence of /autosuggest endpoint calls with its q parameter containing each incomplete textual query: "r", re", "res", rest".

For the 4th character "t", the call looks like:

curl -sD /dev/stderr "https://autosuggest.search.hereapi.com/v1/autosuggest?apiKey=$API_KEY
&at=52.5044,13.33673
&limit=5
&q=rest" | jq .

The API responds with:

HTTP/1.1 200 OK
X-Correlation-ID: c40f3ffa-a672-449a-8d1a-7904f0265e18
(...)

{
  "items": [
    {
      "title": "Restaurant",
      "id": "here:cm:ontology:restaurant",
      "resultType": "categoryQuery",
      "href": "https://autosuggest.search.hereapi.com/v1/discover?at=52.5044%2C13.33673&limit=5&q=Restaurant&_ontology=restaurant",
      ...
    },
    {
      "title": "Marjellchen (Restaurant Marjellchen)",
      "id": "here:pds:place:276u336x-1e3dc04849204f10a3643af8f781e36e",
      "resultType": "place",
      ...
    },
    {
      "title": "Daitokai (Sreh Service Restaurant Exclusiv)",
      "id": "here:pds:place:276u336x-6bc24e93557a4b698ceeb8e8a6aad044",
      "resultType": "place",
      ...
    },
    {
      "title": "Tim Raue (Restaurant Tim Raue)",
      "id": "here:pds:place:276u33d8-a13306b80ec441b2852f80b3e3d63f07",
      "resultType": "place",
      ...
    },
    {
      "title": "Scandic Berlin Potsdamer Platz (Restaurant 3rd Floor)",
      "id": "here:pds:place:276u33d8-dd36958c73714b83ac51aaae16945635",
      "resultType": "place",
      ...
  ],
  "queryTerms": [ ]
}

Notes:

• results may vary as HERE Geocoding and Search constantly improves its ranking algorithms
• The X-Correlation-ID value differs in each API response.

Example: User Action on Autosuggest Result

When an end-user selects the "Restaurant" suggestion (the first result from the example above) on Sat Dec 04 2022 at 10:56 CET, the application performs the following steps:

1. Collect the necessary attributes from the previous response along with the action:

   field	value
   timestamp	1670147788781
   correlationId	c40f3ffa-a672-449a-8d1a-7904f0265e18
   resourceId	here:cm:ontology:restaurant
   rank	0
   action	here:gs:action:view

2. Send a /signals request similar to:

   Shell

   curl -sXPOST "https://signals.search.hereapi.com/v1/signals?apiKey=$API_KEY" -d @- << EOF
   version=1
   &timestamp=1670147788781
   &resourceId=here:cm:ontology:restaurant
   &correlationId=c40f3ffa-a672-449a-8d1a-7904f0265e18
   &rank=0
   &action=here:gs:action:view
   EOF

3. Proceed with the follow-up request specified in the href element of the response.

4. For any subsequent item selections, send related /signals endpoint calls.

Any item returned by Autosuggest—whether a suggested location or a follow-up query—can be the subject of user actions.

For a general overview of the /autosuggest endpoint, see Autosuggest.

📘

Note

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