Hands On

Finding my Dream Home with Isoline Routing

By Richard Süselbeck | 07 August 2018

Try HERE Maps

Create a free API key to build location-aware apps and services.

Get Started

I went to my local bakery recently to get some sugary treats in order to celebrate the launch of our new Freemium plan and I made two observations.

First, Berliners insist on calling a Berliner a Pfannkuchen and I’m sorry but that’s just wrong. (If you’re not German, this probably doesn’t make sense to you. You can safely move on, this paragraph is in fact entirely irrelevant for anything to follow.)

Second, I don’t live in a good neighborhood. I can tell, because I paid with a 10€ bill and the lady at the bakery ran it through a machine to check if it was counterfeit. Let that sink in. I live in a place where people pay for bread with fake 10€ bills.

We’ve been thinking about moving, and I can't say that this incident has done much to change my mind.

That’s not to say that moving is easy. As with many things, location matters. For example, we’d like to move to a location where drunk Dutch teenagers don’t vomit on the sidewalk quite so much. In fact, I’d probably prefer a place entirely devoid of drunk Dutch teenagers or the buses the come in on.

More importantly (and like most people), I’d like to live in a place from where I can get to the office in finite time.

30 minutes is fine. More than that and those Dutch teenagers don’t seem so bad anymore. Unfortunately, it can be a bit of chore to figure out how of a drive it is to the office, when looking at a lot of apartments.

Fortunately, I’m a developer and I have access to the world’s greatest location technology platform. Surely there’s an API that can help?

First, don’t call me surely. Second, there really is an API for that! Meet Isoline Routing, a pretty neat feature hiding in our powerful Routing API. What Isoline Routing does, is to give you an area that can be reached within a certain time frame or driving distance. (By the way, Isoline Routing used to be one of our advanced APIs, unavailable even through our paid plans, but with our new Freemium you can now call this API 250.000 times a month. For free! How neat is that?)

As an example, consider a ride hailing app. When a user calls for a ride, you may want to check with all drivers who are no more than 5 minutes away if they want to accept this ride or not.

Now you could simple ask all drivers within a certain radius. This seems fine, but what if one of those drivers is on the other side of the river? She probably won’t reach the customer for a long time. Unhappy customer, unhappy driver, not a great choice.

You could also call the Routing API for every single driver (maybe bounded by some radius) to check driver availability, but that’s inconvenient and slow.

What you should do instead is use the Isoline feature of the HERE Routing API to find the area from which the customer can be reached in five minutes. Once you’ve done that you can simply ask all drivers within that area whether they want to accept the ride or not.

Here’s an example from London, with someone hailing a ride near the National Theatre after suffering through a performance of War Horse, having been dragged there by a friend who really should have known better.


As you can see, five minutes of driving doesn’t get you very far in London, and it certainly doesn’t get you on the other side of the Thames, so good thing we didn’t just use a radius.

Anyway, back to apartment hunting (and let’s take a moment to be grateful we’re not looking for an apartment in London). We can apply the same principle to our search. For example, we could only consider apartments that are within a 30 minute drive of the office.

Let’s have a closer look at the Isoline Routing API and build a little application in JavaScript to help us do this.

First, we need to set up a map. You can check out the JavaScript Maps API documentation for more details on this.

Then we need to create an instance of our routing service.

Whenever we click on the map we want to see a 30 minute isoline around that location, so we need to register the ‘tap’ event with the map to react to the user’s click.

The ‘tap’ event gives us the screen coordinates of where the user clicked, so we need to convert that to latitude and longitude in order to use it in the Isoline API call. The screenToGeo() method does just that.

To start our Isoline Routing API call, we need to first set up our routing parameters and then call the function calculateIsoline on the routing service instance we’ve created earlier, providing callbacks for the results and errors respectively. Let’s look at these parameters now.

mode: Isoline Routing supports car and pedestrian modes. We can also choose whether to take traffic into account. Since traffic plays a big part in our commute, we want to enable this.

start: The location of our office from which we’re trying to reach our apartment. You can also replace this with destination if your looking for all roads from which you can reach this office within 30 minutes (this is what we would have chosen for our ride hailing use case earlier). This may seem like the same thing, but one-way streets, etc. can lead to different results. You may want to check both for your commute.

departure: This is an optional parameter which let’s you set the time of departure. This matters for traffic. You probably want to check for results during rush hour. Play with this parameter to see how traffic patterns change the results during the day.

rangetype: This determines whether you want to create an isoline for time or distance. For our commute we mostly care about how much time we’re spending in the car, not how long the drive is. If you care mostly about fuel economy, you can also search for consumption.

range: In our case, the range is the time we are willing to drive. This is in seconds, so for 30 minutes we need to set it to 1800.

There are many more parameters, so please check out the Routing API documentation for more details.

Finally, we need to handle the response and draw the isoline on the map so we can compare it against apartment locations. We’re not going to go too much into detail here, so again check out the documentation for more info on how to draw shapes on the map.

If we run this, we should now be able to click on the map and get an isoline. Even better, we can click again and get another isoline! After all, your significant other probably has a job and an office, too. That way you see where the isolines overlap and can find the perfect place to live.


Well, “perfect”. Unfortunately the API currently does not take the density of drunk Dutch teenagers into account. We’re working on it.