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:

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:

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:

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

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: