Geocoding and Search

Resolving addresses to geo-coordinates and vice-versa are common requirements for location-based applications. The HERE Geocoding and Search API unlocks the search and geocoding capabilities of HERE services to provide developers with unmatched flexibility to create differentiating location-enabled applications.

It also supports a reverse geocoding (obtaining a street address that corresponds to a set of geo-coordinates) as well as landmark geocoding (finding airports or landmarks classified as nationally important).

All these features can be accessed through the Map API's service module (mapsjs-service.js) for easy integration into a map application.

Displaying geocoding results on a map

The following example shows how to geocode the address 200 S Mathilda Ave, Sunnyvale, CA and place a marker at the returned location on the map.

The code submits a geocoding request, providing callback functions to handle the results. The request uses an object literal with members matching the parameter names supported by the HERE HERE Geocoding and Search API. The contents of specified object literal are converted by the Maps API to URL parameters. The parameter object can include any parameters recognized by the HERE Geocoding and Search API.

The request is processed asynchronously, which is why the callbacks are needed. The callback function invoked on success places the marker on the map, while the error callback simply displays an alert.

// Instantiate a map and platform object:
var platform = new H.service.Platform({
  'apikey': '{YOUR_API_KEY}'
});

// Get an instance of the geocoding service:
var service = platform.getSearchService();

// Call the geocode method with the geocoding parameters,
// the callback and an error callback function (called if a
// communication error occurs):
service.geocode({
  q: '200 S Mathilda Ave, Sunnyvale, CA'
}, (result) => {
  // Add a marker for each location found
  result.items.forEach((item) => {
    map.addObject(new H.map.Marker(item.position));
  });
}, alert);

A successful geocoding request allows the code to display a marker for each location found as shown in the image below:

Reverse geocoding map locations

The following example shows how to retrieve the address of the specified position in Berlin, Germany (52.5309°N 13.3847°E). The result is displayed on the map with an info bubble marking the location of the retrieved address.

// Instantiate a map and platform object:
var platform = new H.service.Platform({
  'apikey': '{YOUR_API_KEY}'
});

// Get an instance of the search service:
var service = platform.getSearchService();

// Call the reverse geocode method with the geocoding parameters,
// the callback and an error callback function (called if a
// communication error occurs):
service.reverseGeocode({
  at: '52.5309,13.3847,150'
}, (result) => {
  result.items.forEach((item) => {
    // Assumption: ui is instantiated
    // Create an InfoBubble at the returned location with
    // the address as its contents:
    ui.addBubble(new H.ui.InfoBubble(item.position, {
      content: item.address.label
    }));
  });
}, alert);

Autosuggest

The autosuggest endpoint improves user's search experience by allowing submittal of free-form, incomplete and misspelled addresses or place names to the endpoint.

The following example shows how to search for Chicago O'Hare International Airport (ORD).

// Instantiate a map and platform object:
var platform = new H.service.Platform({
  'apikey': '{YOUR_API_KEY}'
});
// Get an instance of the search service:
var service = platform.getSearchService();

// Call the "autosuggest" method with the search parameters,
// the callback and an error callback function (called if a
// communication error occurs):
service.autosuggest({
  // Search query
  q: 'Chicago ORD',
  // Center of the search context
  at: '38.71014896078624,-98.60787954719035'
}, (result) => {
  let {position, title} = result.items[0];
  // Assumption: ui is instantiated
  // Create an InfoBubble at the returned location
  ui.addBubble(new H.ui.InfoBubble(position, {
    content: title
  }));
}, alert);

When the request is successful, the callback function displays an info bubble on the map: