Hands on

Who wants ice cream!? — A HERE Maps API for JavaScript Tutorial (Part 2: Geolocation)

By Richard Süselbeck | 18 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 the previous and very first post in our series we've learned how to acquire credentials for HERE's API services, render a basic map view, control the maps basic functionality through code and how to place a marker with a custom icon. If you haven't read it — we'd recommend to check it out before moving on.

In this post we will request the user's current physical location via his or her web browser's geolocation API and update the map accordingly. Sounds good? Let's get to it!

Browser Geolocation API

The Geolocation API has been supported by browsers for quite some time. Even Internet Explorer has enabled its use since version 9.

The API may be accessed from within our JavaScript code using the global navigator.geolocation object.

Before we start using this API in our little app, let's take a look at some of its methods. Them method names give a good idea as to what they do:

Method Description
getCurrentPosition() Obtain the user's current location.
watchPosition() Watch the user's location and trigger a callback every time it changes.
clearWatch() Stop watching a user's location.

Let's start by looking at getCurrentPosition. This method gives us the current geolocation of a device. It takes three arguments:

  • The success callback function which takes a position object as input parameter.
  • The error callback function which takes an error object as input parameter.
  • And an options object for further configuration options.
  navigator.geolocation.getCurrentPosition(success[, error[, options]]);
view raw gelary-part2-1.js hosted with ❤ by GitHub

However, the getCurrentPosition will give only give you a user's location once. This won't do for our little ice cream delivery application — we want to know where we are at all times while we're racing to deliver the cold goods!

This is where watchPosition comes into play. This method takes exactly the same arguments as getCurrentPosition but the success function will be called every time the position of the device changes.

Great! Let's start using this handy API in our application. In scripts/app.js add the following lines at the bottom:

  function updatePosition (event) {
  var HEREHQcoordinates = {
  lat: event.coords.latitude,
  lng: event.coords.longitude
  };
   
  var marker = new H.map.Marker(HEREHQcoordinates);
  map.addObject(marker);
  map.setCenter(HEREHQcoordinates);
  }
   
  navigator.geolocation.watchPosition(updatePosition);
view raw gelary-part2-2.js hosted with ❤ by GitHub

It's really that simple! This short piece of code will re-center the map every time the user's position changes and render a marker for the new location. Excellent!

When you go and refresh your browser you will likely be asked for permission to use your location via a small dialog in order to protect your privacy:

permissions_dialog.png

Note: We recommend to use Firefox for this tutorial as Google Chrome restricts the use of the Geolocation API if requested from a file:/// URI. If you'd like to continue to use Chrome for we recommend to use a small development server locally.

Pro tip: watchPosition returns an id which may be used to call clearWatch later in order to stop watching for location updates:

  var watchID = navigator.geolocation.watchPosition(function(position) {
  // Do something interesting here
  });
   
  // … later
   
  navigator.geolocation.clearWatch(watchID);
view raw gelary-part2-3.js hosted with ❤ by GitHub

Wrapping up

Today we have learned to create another important piece of our ice cream delivery app: figuring out where we. A few small lines in our code, a giant leap towards am ice cream-driven economy. In the next post we are going to explore how to navigate on a map and how to find routes. Stay tuned!