Places (Search) API Developer's Guide

Search as You Type with Autosuggest

User Story

A user of an application on a mobile device wants to be able to preform a text-based search by selecting from suggestions offered by the application on the basis of his/her partial text entries. The suggestions are refined as the user continues to type and select from them until the user stops typing and submits a query.

Request

The request based on the above user story needs to be made against the endpoint named autosuggest – it is a request for suggestions. The user text entries are submitted as values of the parameter q.

Here is an example of a request based on the text "mc" typed in by the user, standing in Bryant Park in New York:

https://places.cit.api.here.com/places/v1/autosuggest
        ?app_id={YOUR_APP_ID}
        &app_code={YOUR_APP_CODE}
        &at=40.7539,-73.9837
        &q=mc
        &pretty
      
If required, the application developer can refine this request through the parameter result_types to restrict the autosuggest response to specific types of suggestions. The possible values are address, place, category, chain or query.

Here is a version of the same request, using result_types to confine the suggestions to address and query:

https://places.cit.api.here.com/places/v1/autosuggest
      ?app_id={YOUR_APP_ID}
      &app_code={YOUR_APP_CODE}
      &at=40.7539,-73.9837
      &q=mc
      &result_types=address,query
      &pretty
        

Response

The body of the response to the query that chooses only address and query suggestions contains the element "results" shown below – subject to modifications (see Examples) . The result items highlight the user's text entries and indicate completions. The application developer can use the href attributes to trigger a further autosuggest request on any of the completions selected by the user.

{
  "results":[
    {
      "title":"mcdonald",
      "highlightedTitle":"<b>mc</b>donald",
      "completion":"donald",
      "href": "http://...",
      "type":"urn:nlp-types:autosuggest",
      "resultType":"query"
    },
    {
      "title":"mccarthy",
      "highlightedTitle":"<b>mc</b>carthy",
      "completion":"carthy",
      "href": "http://...",
      "type":"urn:nlp-types:autosuggest",
      "resultType":"query"
    },
    {
      "title":"mcguinness",
      "highlightedTitle":"<b>mc</b>guinness",
      "completion":"guinness",
      "href": "http://...",
      "type":"urn:nlp-types:autosuggest",
      "resultType":"query"
    },
    ...
  ]
}