Autosuggest

The /autosuggest endpoint improves user search experience by using free-form, incomplete and misspelled addresses or place names. This suggestion engine is used in the backend of the HERE WeGo and HERE Navigation applications.

Suggestions

Generally, HERE Geocoding and Search is intended to provide a relevant response to user queries.

Queries consist of the following types:

• unknown places of a certain category or chain, such as "restaurants" or "starbucks".
• known locations of a certain name, such as "Eiffel Tower" or "Berlin"
• unknown places at a known location, such as "restaurants Chicago"

Autosuggest provides relevant suggestions to partial queries, such as "restaur", "starbu", "eiffel", or "berl", or "restaurants chica". These suggestions consist of the following types:

• query result items:

  If relevant follow-up queries are found for the partial query. Follow-up queries are either of the following types:

  • place category queries (of result type categoryQuery)
  • place chain queries (with a type chainQuery).

• entity result items

  If relevant places or address objects are found for the partial query. The result type consists of one of the following: addressBlock, administrativeArea, houseNumber, intersection, locality, place, street.

The "restaurant" suggestion in the previous image is from an Autosuggest query result item.

Follow-up request

The /autosuggest endpoint supports end-user interaction with a text-based input engine. Requests to the /autosuggest endpoint are sent for each key-stroke, beginning with the first.

Each returned item contains the necessary information to build follow-up queries:

• Query items contain an href element containing a follow-up query to /discover
• Entity items contain a location id usable through the /lookup endpoint

Note that when Autosuggest only returns a query item, applications can proceed with the /discover follow-up query without waiting for the end-users to select it. This is recommended to increase application responsiveness. Note also that the id field returned in the Query items cannot be used on the /lookup endpoint, unlike the id field in the Entity items.

Follow-up to /discover

For example, if HERE WeGo users tap on a query result item such as the "restaurant" suggestion in the image, above HERE WeGo displays the related restaurant search results:

HERE WeGo uses the restaurant suggestion href field to send a follow-up query to the search backend.

📘

Note:

If API key authentication is used, the client must add the apiKey parameter to any query result item returned by autosuggest. See Get Credentials for details on authentication methods.

Follow-up to /lookup

Tapping on a suggestion such as the restaurant, "Tomate Fresh Kitchen", displays related information. HERE WeGo calls /lookup with the related entity result id. See the following image:

Location context

Queries to /autosuggest require the same type of location context as the /discover endpoint, through the use of the at, in or route parameters.

Query string

The q parameter is used to submit the developing phrases, one Autosuggest query per additional key-stroke.

For example, if an end-user uses the application, they might intend entering the letters r, e, s, t, a, u, r, a, n, t. The application sends a request with a q parameter set to "r", then "re", "res", "rest", etc. The customer can decide to send Autosuggest queries starting with the first key-stroke to provide early suggestions. You can also send queries starting with the 3rd key stroke. In that case, the example queries would have a q set to "res", "rest", etc.

For discover, the input string can be formed in various and mixed scripts (Latin, Cyrillic, Arabic, Greek, ...).

Special cases:

• q values are expected to be non-empty.
• q values only containing whitespaces, or tabs, or line feeds are valid queries and return empty results lists.

For example, a query for "rest" suggestions somewhere in Baltimore is as follows:

GET https://autosuggest.search.hereapi.com/v1/
    autosuggest
    ?at=39.31974,-76.56721
    &limit=5
    &q=rest
    &apiKey={YOUR_API_KEY}

Result items fields

The suggestion engine returns a set of relevant suggestions, either query or entity items. More details about /autosuggest parameters can be found in the API Reference.

The response to a request similar to the one sent by the HERE WeGo application in the example, above is as follows:

{
  "items": [
    {
      "title": "Restaurant",
      "id": "here:cm:ontology:restaurant",
      "resultType": "categoryQuery",
      "href": "https://autosuggest.search.hereapi.com/v1/discover?at=39.31974%2C-76.56721&limit=5&q=Restaurant&_ontology=restaurant",
      "highlights": { "title": [{ "start": 0, "end": 4 }] }
    },
    {
      "title": "Rest stop",
      "id": "here:cm:ontology:rest_area",
      "resultType": "categoryQuery",
      "href": "https://autosuggest.search.hereapi.com/v1/discover?at=39.31974%2C-76.56721&limit=5&q=Rest+stop&_ontology=rest_area",
      "highlights": { "title": [{ "start": 0, "end": 4 }] }
    },
    {
      "title": "Restoration East",
      "id": "here:pds:place:840dqcx9-2f1561a4501b4cc0a49aa6611838b448",
      "resultType": "place",
      "address": { "label": "Restoration East, 4209 E Chase St, Baltimore, MD 21205-3020, United States" },
      "position": { "lat": 39.30398, "lng": -76.56193 },
      "access": [{ "lat": 39.30435, "lng": -76.56264 }],
      "distance": 1810,
      "categories": [{ "id": "700-7400-0000", "name": "Consumer Services", "primary": true }, { "id": "700-7200-0277", "name": "Specialty Trade Contractors" }],
      "highlights": { "title": [{ "start": 0, "end": 4 }], "address": { "label": [{ "start": 0, "end": 4 }] } }
    },
    {
      "title": "Rent Now (Rest for the Wicke)",
      "id": "here:pds:place:8403fv6k-b6fd543c49df01f3ae3981be17ed3412",
      "resultType": "place",
      "address": { "label": "Rent Now, 5229 Harford Rd, Baltimore, MD 21214-2622, United States" },
      "position": { "lat": 39.34978, "lng": -76.56321 },
      "access": [{ "lat": 39.34991, "lng": -76.56347 }],
      "distance": 3358,
      "categories": [{ "id": "700-7400-0145", "name": "Real Estate Services", "primary": true }, { "id": "600-6950-0000", "name": "Hair & Beauty" }, { "id": "700-7400-0000", "name": "Consumer Services" }],
      "highlights": { "title": [{ "start": 10, "end": 14 }], "address": { "label": [ ] } }
    },
    {
      "title": "Prorest Pest (Pro Rest Pest)",
      "id": "here:pds:place:840dqcxd-2a86850c1c34418f8023280a5f7baf62",
      "resultType": "place",
      "address": { "label": "Prorest Pest, 6600 Frankford Ave, Baltimore, MD 21206-4901, United States" },
      "position": { "lat": 39.31265, "lng": -76.54259 },
      "access": [{ "lat": 39.31285, "lng": -76.54273 }],
      "distance": 2260,
      "categories": [{ "id": "700-7200-0277", "name": "Specialty Trade Contractors", "primary": true }, { "id": "550-5520-0210", "name": "Wildlife Refuge" }, { "id": "700-7400-0000", "name": "Consumer Services" }],
      "references": [{ "supplier": { "id": "yelp" }, "id": "BY3MjxFzBwCl_OemyfJBKQ" }],
      "highlights": { "title": [{ "start": 3, "end": 7 }, { "start": 18, "end": 22 }], "address": { "label": [{ "start": 3, "end": 7 }] } }
    }
  ],
  "queryTerms": [ ]
}

Common elements

The response includes multiple items from the top choice to least-likely match.

It delivers the following high-level elements for each item:

• resultType - the item type

  HERE Geocoding and Search /autosuggest is able to return items of several types:

  categoryQuery, chainQuery, place, locality, etc.

• title – a representative string for the item

  For example, the name of a place, or the title of a suggestion follow-up query

• id - the identifier of the item

  If the item is not of type categoryQuery, chainQuery, the id value can be used to retrieve the same object through the /lookup endpoint.

Query results items

Query suggestions specific elements:

• href - follow-up query URI

  This query will be used by the application if the end user chooses the related item. Follow-up queries are either category queries or chain queries.

• highlights - the text slices matching the query

  These slices can be used to highlight the related matching fields.

Entity results items

Places and address suggestion specific elements:

• position - a representative geo-position (WGS 84) of the result. this is to be used to display the result on a map
• access - the geo-position of the access to the result (for instance the entrance)
• distance - the distance in a straight line in meters from the position specified in the query at parameter
• address.label - the full address of the entity result item

Results of type place may have additional attributes as listed out in Place results.

Query term completion support

To support end-users to formulate a free-form textual query, /autosuggest provides a list of complete terms end-users can pick-up to replace the word they began to enter. The list of predictive text for the last entered word can be found in the queryTerms response element, when the termsLimit query parameter is set to a value larger than 0 (max value is 10).

Note that while items contains result items ready to be used for a complete follow-up query, queryTerms focuses at the query the end-user is formulating. Both arrays are separated to allow a more flexible application user experience.

A full example is available in Query Term Completion.

Preferred language

Applications that require items to be returned in a preferred language must set the lang parameter to the related BCP 47 language code. The Autosuggest service will attempt to return suggestions in that language. If lang is not set, or if the suggestion item has no translation in the requested language, the default language is used.

📘

Note:

Any undocumented response attribute must be considered experimental and is subject to being removed or modified at any time. Feedback is welcome.