Maps API for JavaScript Developer's Guide

Geocoding

Resolving addresses to geo-coordinates and vice-versa are common requirements for location-based applications. The HERE Geocoder API provides a REST service to perform geocoding (matching an address to its correct location on the map), 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 a geocodingParameters object literal whose members match the parameters names supported by the HERE Geocoder API. The contents of geocodingParams are converted by the Maps API to URL parameters. The parameter object can include any parameters recognized by the Geocoder API, offering complete flexibility in defining a route calculation request.

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({
  'app_id': '{YOUR_APP_ID}',
  'app_code': '{YOUR_APP_CODE}'
});
// Retrieve the target element for the map:
var targetElement = document.getElementById('mapContainer');

// Get default map types from the platform object:
var defaultLayers = platform.createDefaultLayers();

// Instantiate the map:
var map = new H.Map(
  document.getElementById('mapContainer'),
  defaultLayers.normal.map,
  {
  zoom: 10,
  center: { lat: 52.51, lng: 13.4 }
  });

// Create the parameters for the geocoding request:
var geocodingParams = {
    searchText: '200 S Mathilda Ave, Sunnyvale, CA'
  };

// Define a callback function to process the geocoding response:
var onResult = function(result) {
  var locations = result.Response.View[0].Result,
    position,
    marker;
  // Add a marker for each location found
  for (i = 0;  i < locations.length; i++) {
  position = {
    lat: locations[i].Location.DisplayPosition.Latitude,
    lng: locations[i].Location.DisplayPosition.Longitude
  };
  marker = new H.map.Marker(position);
  map.addObject(marker);
  }
};

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

// Call the geocode method with the geocoding parameters,
// the callback and an error callback function (called if a
// communication error occurs):
geocoder.geocode(geocodingParams, onResult, function(e) {
  alert(e);
});

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

Figure 1. The map after retrieving the geo-coordinates for the address

Reverse geocoding map locations

The following example shows how to retrieve the first address within a radius of 150 meters of a location 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.

The code places the details of the request in the object named reverseGeocodingParameters and defines callbacks to process both a success and an error response. The success callback creates an info bubble, populates it with the reverse geocoding result and displays the info bubble on the map.

// Instantiate a map and platform object:
var platform = new H.service.Platform({
  'app_id': '{YOUR_APP_ID}',
  'app_code': '{YOUR_APP_CODE}'
});
// Retrieve the target element for the map:
var targetElement = document.getElementById('mapContainer');

// Get default map types from the platform object:
var defaultLayers = platform.createDefaultLayers();

// Instantiate the map:
var map = new H.Map(
  document.getElementById('mapContainer'),
  defaultLayers.normal.map,
  {
  zoom: 10,
  center: { lat: 52.51, lng: 13.4 }
  });

// Create the parameters for the reverse geocoding request:
var reverseGeocodingParameters = {
    prox: '52.5309,13.3847,150',
    mode: 'retrieveAddresses',
    maxresults: 1
  };

// Define a callback function to process the response:
function onSuccess(result) {
  var location = result.Response.View[0].Result[0];

  // Create an InfoBubble at the returned location with
  // the address as its contents:
  ui.addBubble(new H.ui.InfoBubble({
    lat: location.Location.DisplayPosition.Latitude,
    lng: location.Location.DisplayPosition.Longitude
   }, { content: location.Location.Address.Label }));
};

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

// Call the geocode method with the geocoding parameters,
// the callback and an error callback function (called if a
// communication error occurs):
geocoder.reverseGeocode(
  reverseGeocodingParameters,
  onSuccess,
  function(e) { alert(e); });
Figure 2. The map showing the retrieved address of a location

Landmark search

Landmark geocoding is a combination of geocoding, landmark search, and reverse geocoding. It supports search for airports, well known landmarks such as the Eiffel Tower or landmarks classified as nationally important. The result is a list of ranked locations including street addresses, administrative areas, or landmarks.

The following example shows how to search for Chicago O'Hare International Airport (ORD) using the landmark search. The object landmarkSearchParameters is used to convey the parameters defining the request to the back end, and the callback methods handle the success and error responses.

// Instantiate a map and platform object:
var platform = new H.service.Platform({
  'app_id': '{YOUR_APP_ID}',
  'app_code': '{YOUR_APP_CODE}'
});
// Retrieve the target element for the map:
var targetElement = document.getElementById('mapContainer');

// Get default map types from the platform object:
var defaultLayers = platform.createDefaultLayers();

// Instantiate the map:
var map = new H.Map(
  document.getElementById('mapContainer'),
  defaultLayers.normal.map,
  {
  zoom: 10,
  center: { lat: 52.51, lng: 13.4 }
  });

// Create the parameters for the landmark search request:
var landmarkSearchParameters = {
  searchText: 'ORD'
};

// Define a callback function to process the search response:
function onSuccess(result) {
  var location = result.Response.View[0].Result[0].Place.Locations[0];

  // Create an info bubble at the retrieved location with the
  // location's name as contents:
  ui.addBubble(new H.ui.InfoBubble({
  lat: location.DisplayPosition.Latitude,
  lng: location.DisplayPosition.Longitude
   }, { content: location.Name }));
};


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

// Call the geocode method with the search parameters,
// the callback and an error callback function (called if a
// communication error occurs):
geocoder.search(landmarkSearchParameters, onSuccess, function(e) {
  alert(e);
});
When the request is successful, the callback function displays an info bubble on the map:

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.