Hands on

Who wants ice cream!? — A HERE Maps API for JavaScript Tutorial (Part 1: Basic Map Set-up)

By Richard Süselbeck | 05 October 2016

 Who wants ice cream?! — In this series of tutorial blog posts we are going to develop a small web application called “Gelary” using the HERE Maps API for JavaScript. Gelary aims to disrupt the ice-cream market by enabling ice-cream producers to deliver their sweet goods directly to their customers, wherever they are.

The final application will be a mobile dashboard view for the employees of our little start-up which they can either take on the road or use at Gelary HQ to plan their work. It will consist of a map and a floating control panel behind a menu button. The map is used to visualise a route, starting from the user's current position along a series of customers, and the traffic situation along the route. The control panel will enable our delivery drivers to search for nearby ice cream shops, display turn-by-turn directions as well as to calculate the best pick-up location for a group of selected customers. The app will also be able to handle order changes: e.g. if a customer cancels or updates his or her position, the route will automatically be recalculated.

To keep things simple our application will use plain JavaScript (ES5) and front-end technologies and will target mobile and desktop browsers alike.

What will we learn in this tutorial?

In this first post we'll setup our work environment and acquire credentials for the HERE APIs. Once everything is up and running we'll learn how to render a basic map view, control the map's basic functionality through code and how to place a marker with a custom icon.

Acquiring credentials for the HERE API

The very first thing we need is to create a HERE account and register our application — no worries, this will just take a moment. Our 90-day free trial will do nicely for this tutorial (and a lot more). After signing up for our account we create a new application and select a name for it. Once that's done, we'll receive two important pieces of information: An "app ID" and an "app code". (You can always looks these up in your account.)

Setting up the skeleton of our app

Once we are all done registering our application, we can finally get our hands dirty and start building our app. (By the way, all the source code is available on GitHub to follow along easily.

The HERE Maps API for JavaScript is split into multiple modules. This allows us to only include in our project what we actually need. Here are the different modules we will use in our application:

File(s) Description
mapsjs-core.js Core API, provides core functionality for rendering maps, map layers and map objects.
mapsjs-service.js Provides tile retrieval, routing and geocoding.
mapsjs-mapevents.js Provides functionality for user interaction.
mapsjs-ui.js + mapsjs-ui.css Provides user interface for e.g. map settings, zooming and so on.

Let's get coding! We start out by creating an index.html file with a simple HTML structure including script and style tags for the HERE Javascript SDK modules within the <head> tag:

  <link rel="stylesheet" type="text/css" href="https://js.api.here.com/v3/3.0/mapsjs-ui.css" />
  <script type="text/javascript" charset="UTF-8" src="https://js.api.here.com/v3/3.0/mapsjs-core.js"></script>
  <script type="text/javascript" charset="UTF-8" src="https://js.api.here.com/v3/3.0/mapsjs-service.js"></script>
  <script type="text/javascript" charset="UTF-8" src="https://js.api.here.com/v3/3.0/mapsjs-ui.js"></script>
  <script type="text/javascript" charset="UTF-8" src="https://js.api.here.com/v3/3.0/mapsjs-mapevents.js"></script>

In the <body> tag we then add a container for the map — a <div> tag — into which the map will be embedded.

  <div id="map-container” class="map"></div>

Pro tip: In this example we use script tags and static <div> placeholders within our index.html file but the same approach applies if you want to use a JavaScript framework.

Displaying a basic map

Once you open index.html in your browser you will notice that so far we're stuck with an empty white page — let's change that! We proceed by creating a folder called scripts and a file app.js inside this folder. We then add the code to initialise our map to this file:

  var platform = new H.service.Platform({
  app_id: '{YOUR_APP_ID}', // // <-- ENTER YOUR APP ID HERE
  app_code: '{YOUR_APP_CODE}', // <-- ENTER YOUR APP CODE HERE
  });
   
  var defaultLayers = platform.createDefaultLayers();
  var mapPlaceholder = document.getElementById('map-container');
   
  var map = new H.Map(
  mapContainer,
  defaultLayers.normal.map);
view raw gelary-part1-3.js hosted with ❤ by GitHub

Let's also make sure that the map reacts properly when the window is resized. For this purpose we add the following event listener below our map initialisation.

  window.addEventListener('resize', function () {
  map.getViewPort().resize();
  });
view raw gelary-part1-4.js hosted with ❤ by GitHub

Going further, we include the newly created file in our index.html just before the closing </body> tag:

  <script src="scripts/app.js"></script>

In order to control the visual appearance of the map, let's also add a dash of CSS. Go ahead and create a folder styles and a file main.css with the following content inside this folder:

  .map {
  width: 100vw;
  height: 100vh;
  position: relative;
  }

This piece of code will ensure that the map always fills the viewport completely.

Now go and refresh your browser window and you should see your beautiful map. Well done!

Basic Map

Interacting with the map

While certainly pretty, our map is frankly not very useful yet. Furthermore, the map center seems fairly randomly selected and zooming in or out is not possible either.

Let's add some interactivity by enabling the event system. In order to do so, add following line just after the initialization of the map inside scripts/app.js.

  var behavior = new H.mapevents.Behavior(new H.mapevents.MapEvents(map));
view raw gelary-part1-7.js hosted with ❤ by GitHub

And that's it. Now we can at least move around the map as well as zoom in and out. 

Let's adjust the center point of the map and the initial zoom level of the map as well. This can be done by passing a options object to the constructor H.Map when initialising the map.

  var coordinates = {
  lat: 52.530974, // HERE HQ in Berlin, Germany
  lng: 13.384944
  };
   
  var mapOptions = {
  center: coordinates,
  zoom: 14
  }
   
  var map = new H.Map(
  mapContainer,
  defaultLayers.normal.map,
  mapOptions);
view raw gelary-part1-8.js hosted with ❤ by GitHub

Alright, things are starting to shape up nicely!

Pro tip: You can set the map's center pointer and zoom level using map.setCenter and map.setZoom methods at any point in your code.

Adding markers to the map

In the future we will want to highlight locations such as customers or deliveries on the map using place markers. This is easily done using HERE maps. All we have to do is instantiate a new Marker object by passing in the appropriate coordinates and calling map.addObject. Let's try it in our scripts/app.js file:

  var marker = new H.map.Marker(coordinates);
  map.addObject(marker);
view raw gelary-part1-9.js hosted with ❤ by GitHub

After refreshing the browser window you should see a marker marking in the middle of the map.

Map with marker

Pro tip: While map.addObject adds new markers, you can remove them again using map.removeObject.

Custom icons for markers

Gelary's designers have done an amazing job with the user interface, but they want us to display customer marker icons. As it turns out, that's not a problem. The Marker constructor takes an options object as a second argument. This allows us to define a custom icon, using the H.map.Icon class:

  var iconUrl = ‘./images/marker-gelato.svg’;
   
  var iconOptions = {
  // The icon's size in pixel:
  size: new H.math.Size(26, 34),
  // The anchorage point in pixel,
  // defaults to bottom-center
  anchor: new H.math.Point(14, 34)
  };
   
  var markerOptions = {
  icon: new H.map.Icon(iconUrl, iconOptions)
  };
   
  var marker = new H.map.Marker(coordinates, markerOptions);
  map.addObject(marker);

Looks great!

Map with custom marker

Wrapping up

For now we have set up a very basic interactive map sporting a marker with a custom icon. This work will be the foundation of our amazing ice cream delivery platform.

In the next post we are going to integrate with the browser's geolocation API to keep the delivery drivers updated. Stay tuned!