Places (Search) API Developer's Guide

Making Your First Request

Once you have application credentials, you can make your first request to the Places (Search) API.

First you need to connect to the appropriate server. As mentioned in greater detail in Testing An App, the Places (Search) API, we provide a dedicated environment for customer integration testing (CIT). The CIT environment is available to help you get familiar with the API and assist you during the development of your applications. The production environment should only be accessed from shipped applications.

Since we are working with the API for testing purposes we make requests to the CIT environment. In order to access the CIT environment, use the URL https://places.cit.api.here.com.

Making a Request for Finding a Place using a Text String

Now, imagine you want to build an application for a smart device or browser where the application always display a map to the user and a user can type a search term in an input field to find a specific place. In order to build such an application, we will need a location context for the area that the user wants to query. There are many possibilities how to provide a location context, see Best Practice for more detail about what location context to send. Let's assume that the user can set a location context explicitly by clicking in that app somewhere in the middle of Manhattan, where the geolocation is latitude 40.74917 and longitude -73.98529.



Based on that geolocation information, we can implement our first feature with the Places (Search) API by using the autosuggest entrypoint:

Note: We are using the autosuggest entrypoint because it was specifically designed for returning instant search results, exploratory search and refined search query suggestions as user types.
https://places.cit.api.here.com/places/v1/autosuggest
  ?at=40.74917,-73.98529
  &q=chrysler
  &app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
  &tf=plain
  &pretty=true
      

As you can see, the request URI contains a request to the CIT environment through the autosuggest entrypoint (https://places.cit.api.here.com /places/v1/autosuggest), followed by several query string parameters:

at
The selected geo-coordinate as latitude, longitude (in this case where the User has clicked)
q
The plain-text search term.
app_id, app_code
The credentials required to identify the app (see Acquiring Credentials)
tf
A flag that switches the presentation of rich text elements to plain text for better readability
pretty
A flag to enable pretty printing (so that we can read the result better)

You can find out more about the various parameters that can be used to influence the returned representation in Representation Modifiers. For now, we are using an example with some of the most common parameters and headers.

Breaking Down the JSON Response

The default response representation for all Search & Discovery entrypoints, like the autosuggest entrypoint we used above, is application/json. However if you use a web browser you will get an HTML representation which is intended for exploring the API.

Note: If an Accept header is set in the request and it does not match */*, application/json or xhtml+xml an HTTP 406 error response - "Not Acceptable" will be returned

When using the URL in your HTTP client or browser for the autosuggest entrypoint, you will receive a JSON document containing a result list of places and refined search queries of this particular query. For example, below is a list of places returned from the CIT environment as rendered by a browser:

{
  "results": [
    { "Chrysler Building" },
    { "Chrysler Camera Repair" },
    { "Manhattan CHRYSLER" },
    { "Chrysler Cleaners Inc" },
    { "Chrysler Stationery & Gift Inc" },
    { "Chrysler Tower Periodontics" },
    { "Major World CHRYSLER" },
    { "Chrysler Auto Repair" },
    { "Hudson CHRYSLER" },
    { "Teterboro CHRYSLER" },
    { "Riverdale CHRYSLER" },
    { "Major CHRYSLER DODGE Jeep" },
    { "Bayside CHRYSLER" },
    { "Star CHRYSLER" },
    { "Route 46 CHRYSLER" },
    { "Chrysler-Plymouth Authorized Sales & Service" },
    { "Monroe" },
    { "Kacey Chrysler" },
    { "Chrysler Rd" },
    { "CHRYSLER" }
  ]
}

As can be seen in the example above, most browsers will return expandable links for each individual place. Once expanded, each of these links displays additional information about that particular place. For example, if a user or application expands the information about the Chrysler Building they will see:

{
  "title": "Chrysler Building",
  "highlightedTitle": "<b>Chrysler</b> Building",
  "vicinity": "405 Lexington Ave\nNew York, NY 10017",
  "position": [ 40.75185, -73.97572 ],
  "category": "sights-museums",
  "href": "https://...",
  "type": "urn:nlp-types:place"
}

Some important fields to note for a suggested place media type response:

  • title gives the name of the place
  • highlightedTitle gives the name of the place with markups highlighting the parts of the string that were matched.
  • vicinity describes of the location of the place; usually derived from the address of the place, but may also contain any other description that helps a user understand where the place is located.
  • position describes the geolocation of this particular place. This geolocation is suitable for displaying the place's position on a map.
  • category explains the relevant category group for that place which helps describe it. All places have a category, for example eat-drink, going-out,sights-museums, and more.
  • href a URI that links to to the resource from where you can fetch more data about that place. For example, this can be used when the user selects that result item. In the above case, since the Media Type is a place, the returned information is additional data about that place (such as contacts, reviews, additional address information, and more)
  • type is a URI that describes the kind of resource (what are called Media Types in the Places (Search) API) that will be returned by the href

Using the Result in your Application

For now, lets concentrate on the most critical of the above fields in order to give the user the results they desire. In order to properly use the place information sent from the server, you will need to:

First, render the entire list of items that are returned in the Autosuggest media type in the User Interface of your application. The Autosuggest media type starts with results, and contains items (the current list of places and refined search suggestions) as seen in the below example:

{
  "results": [
    {
      "title": "Chrysler Building",
      "highLightedTitle": "<b>Chrysler</b> Building",
      "vicinity": "405 Lexington Ave\nNew York, NY 10017",
      "position": [ 40.75185, -73.97572 ],
      "category": "sights-museums",
      "href": "https://...",
      "type": "urn:nlp-types:place"
    },
    {
      "title": "Chrysler Camera Repair",
      "highlightedTitle": "<b>Chrysler</b> Camera Repair",
      "vicinity": "367 W 34th St\nNew York, NY 10001-1647",
      "position": [ 40.753098, -73.995239 ],
      "category": "business-services",
      "href": "https://...",
      "type": "urn:nlp-types:place"
    },
    ...,
    {
      "title": "CHRYSLER",
      "highlightedTitle": "<b>CHRYSLER</b>",
      "href": "https://...",
      "type": "urn:nlp-types:search"
    }
  ]
}

After you have parsed the result list, give users the capability to view information about each of the places on the current list by:

  • rendering each result item in your application's User Interface using hightlightedTitle or title object and vicinity object,
  • using the position of each result item for displaying place position's on a map and
  • providing a link to the href object URI which the user can select
Note: In case the user did not find searched place in autosuggest results, we recommend you to use Search entrypoint in your application User Interface to submit complete search term, for example on Enter key press event.

Just follow the flow

Now that your application's users have seen the suggested results. When a user has found the place, the user (or your application) selects the href URI of the place, a JSON response is given with further data about that place. Each item listed in this response, just like with each individual place, contains a URI that links you to the resource from where you fetch more information when the user selects that result item.

So, in order to allow a user to view any of these items (and any other related items down the line) all you should do is take the URI in the given result item and use it as the next request to the Places (Search) API.

Depending on the type of the selected item, you will then either receive detailed information on the selected place or another search result list for the refined search request. In this example "CHRYSLER" with type urn:nlp-types:search is a refined chain/brand search.

For example, if you take the place information for the Chrysler Building and the user wants more information about that place, then provide the user the option to select the href object (or some kind of UI equivalent, like a button). Once the user makes the selection, send the entire href URI as the next request to the Places (Search) API. The application will then receive a JSON response like the one below:

Note: The response shown here is shortened for the sake of space. See Places Media Type for a full example.
{ 
  "name": "Chrysler Building",
  "placeId": "840dr5ru-08bf72d1a15f41228438fb017f83a84c",
  "view": "http://...",
  "location": { 
    "position": [ 40.7517 , -73.97583 ],
    "address": { 
    "text": "405 Lexington Ave at 42nd St<br/>New York City 10017<br/>USA", 
    "house": 405, 
    "street": "Lexington Ave at 42nd St", 
    "postalCode": 10017, 
    "district": "Midtown Center", 
    "city": "New York City", 
    "country": "USA", 
    "countryCode": "USA" 
    }
  }, 
  "contacts": { 
    "phone": [
      {
        "value": "+12126823070",
        "label": "Phone"
      }
    ],
    "website": [
      {
        "value": "http://en.wikipedia.org/wiki/Chrysler_Building",
        "label": "Website"
      }
    ]
  },
  "categories": [ 
    "{ Going Out }", 
    "{ Landmark/Attraction }",
    "{ Sights & Museums }",
    "{ Theatre, Music & Culture }"
  ],
  "icon": "http://download.vcdn.data.here.com/p/d/places2/icons/categories/05.icon",
  "ratings": { 
     "average": 4.75,
     "count": 8 
  }
}

Now, you display the information received to the user and provide them with links to any further URIs in the response. In turn, with those URIs in that response, provide any displayable information and links to any available URIs. And so on.

Note: Almost every URI has a type field next to it that explains the kind of resource that will be retrieved. These are the above referenced media types. Some non media type objects also contain label fields that provide similar information

This hypermedia mechanism is the most fundamental design principle of the Places (Search) API. You start a usage flow by constructing the URI of the entry point of the use case you want to provide (in the above example, autosuggest) and then display the results to your users. Users then select a hypermedia item they want to know more about and your application just uses the href attribute of the selected item for the next request and then gets access to the required information.

So there's no need to know the URIs for all resources in your application's code. No need to construct a URI with complex URI templates. Just follow the link, and we'll get you where you (and your users) want to be.

Note: Please keep in mind, as pointed out in the User Flow, applications must guide users through a flow of Search &Discovery, Information, and Interaction.

What's Next

As you've learned, the Places (Search) API provides you with a simple to use and consistent skeleton for your application's user experience, yet you still have full control over the actual user interface design.

The hypermedia approach also allows you to easily familiarize yourself with our API: just follow the links in the responses and you'll find most of the things you can use to build your application.

There is only one detail missing before you can build your own application: request your own credentials (see Acquiring Credentials). Your credentials can then be used on both environments: CIT and production. The production domain is:

places.api.here.com

During development, you continue to use the CIT instance, but once you ship your application, you must switch to production. While requests against both environments are subject to the same quota limits, only those against production will be reflected in the application statistics that you find next to your application's registration info. And you don't want to miss the information on how your application is used. Also, the quality of service in terms of availabiltiy and latency is only managed in the production environment.

The Remainder of This Document

While you can learn a lot about the Places (Search) API by just playing with it, we still strongly recommend you read the remainder of this document before you start implementing your application. Your application's extensibility and maintainability will benefit dramatically when you learn about the fundamental design patterns and apply the best practices that we outline in this document.

Also, you may want or need to leave the regular path outlined by the hypermedia links of the system. While your application will never have to give up the beauty of the hypermedia pattern, we provide you with simple mechanisms to adjust the behavior of the system to your application's needs.

You'll find this information in the following chapters:
  • Core API Features provides an in-depth tutorial for developers that guides you through the concepts and best practices of the Places (Search) API using several simple examples.
  • References includes a detailed specification of all entry points, data types and other elements that comprise the Places (Search) API.

Additional Resources

Playground

You can browse an HTML representation of the API to get a feel for what it provides. Just point a browser to

https://places.cit.api.here.com/places
stackoverflow
We would love to get your feedback about Places (Search) API. Please join the conversations in the developer forum

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.