Isochrones using the Google Maps Distance Matrix API


by Drew Fustin |

About Drew: Drew is the Lead Data Scientist at SpotHero, an on-demand answer to assist drivers discover their excellent parking spot, reserved forward of time usually at charges a lot decrease than you’d discover in case you simply drove as much as the storage. He’s additionally labored at Digital H2O and GrubHub. Drew lives along with his spouse Alexis and daughter June in Chicago’s West Loop neighborhood.

Isochrones using the Google Maps Distance Matrix API

[tl;dr] I wrote a Python module referred to as isocronut that may calculate isochrones round an origin level.

I stay in a neighborhood in Chicago that’s near just about all the things,
as is the case with many prosperous neighborhoods in large cities…and, sadly,
not the case in the poorer neighborhoods.
But, in the case of the West Loop, that is significantly true. For occasion, I’m inside strolling distance
of the eating places of two of the 5 “Best Chef: Great Lakes” nominees for
this yr’s James Beard Awards (final yr, it was Three of the 5). Fittingly
sufficient, I’m additionally inside strolling distance of this yr’s James Beard Awards —
they’re being held at the Lyric Opera in a pair weeks, which is alongside my
stroll to work.

When my spouse and I have been deciding on the place to purchase in Chicago, an enormous issue —
together with high quality of the neighborhood public college — was the walkability of
the space and the proximity to the trains (for her commute) and the Loop
(for mine). And, when fascinated with how lengthy it takes to journey a sure
distance, both on foot or in the automobile, it is sensible to contemplate one thing
referred to as an isochrone. An isochrone is a contour that may be drawn round an
origin level (e.g. our apartment) that connects factors of equal journey time.
So, as an illustration, I can stroll to any level alongside the border of the contour
under in 15 minutes (and anywhere inside that contour in lower than 15 minutes).
And, no that isn’t my precise tackle — however it’s the tackle of a Harold’s
Chicken Shack
, which is kind of great.

(Aside: sadly, Harold’s Chicken West Loop has closed since this was first written. Fret not, Harold’s is shifting to 1501 W Madison Street. Stay tuned for updates.)

Google Maps API Access

In order to generate isochrones equivalent to these, I made use of the Google Maps API.
If you have by no means used the Google Maps API earlier than, properly then, buddy, now’s your
likelihood. It’s not overly tough, nevertheless it does have some difficult moments. If
you are accustomed to this API (and even APIs, basically), you may most likely
determine the subsequent a number of paragraphs your self. I’ll save your eyes from glazing
over — skip forward to whichever part appears least boring to you.

If you could have a Google Maps API for Work, you are in luck! On one hand,
you could have a lot softer utilization limits in place. In addition, you get to utilize
Google’s visitors info, which is extraordinarily helpful in making correct
driving isochrones that line as much as actuality (or any time aside from the
center of the evening when there is not any visitors). But beware that it simply
requires additional safety work from you up entrance. Make observe of your Client ID and
Crypto Key and, for goodness sake, get permission from the correct authorities at
work earlier than using their API key.

If you do not have entry to a Work API, the very first thing that you must do is
get your self a Google Develop mission.
Click “Create Project” and identify it one thing catchy like “Isochrones.”
Once created, you may click on your mission identify, and you may be taken to a
display with a listing on the left containing “APIs & auth” with subheadings
containing “APIs” and “Credentials.” Go to “APIs” and click on “more” beneath
“Google Maps APIs.” For this mission, we’ll make use of each the “Geocoding API”
and the “Distance Matrix API,” so click on on every of these and click on “Enable API.”
Finally, go to the “Credentials” subheading on the left, click on “Create new Key”
beneath “Public API access,” and click on “Browser key” then “Create.”

After all that clicking, your API mission is now arrange with Google. They’ll
use your API key that’s now listed to trace all of your API utilization, to verify
you are not going over your limits. There are limits (the Distance Matrix API
permits solely 100 parts per 10 seconds and a couple of,500 parts per day when you’ve got
a free API). Sometimes this requires you to take a while off. Sometimes it
requires you to gradual your code down. Be conscious.

With the Python module I wrote, I entry these credentials from an exterior
file. If you are so inclined to do the similar as an alternative of hard-coding them in,
open up your editor of alternative and create a file referred to as ‘google_maps.cfg’ that
will include your API key (or Client ID and Crypto Key, in case you are using API
for Work). In a folder you could have famous and might level the script to, make a file
that appears identical to this (leaving some fields clean, relying on in case you are
using the Free or Work API), besides that it truly has your credentials in it:

api_number=<YOUR API KEY>
client_id=<YOUR CLIENT ID>
crypto_key=<YOUR CRYPTO KEY>

Using the Google Maps API

As talked about, we’ll use the Geocoding API and the Distance Matrix API.
The Geocoding API is barely extra straight ahead, so let’s begin there.
This whole mission is hosted on my github account, so I’m simply going to put up
related snippets to clarify the code that’s detailed there (with good feedback!).
Hopefully it is clear sufficient right here.

Geocoding API

The Geocoding API is utilized in reworking a avenue tackle string into its
corresponding [lat, lng] pair. In normal, API use is so simple as making a
URL to go after which studying the JSON (or XML, if that is your alternative) that’s
returned. In this case, take your tackle string (let’s use the Harold’s once more)
and substitute any house with a +, like so: ‘tackle=804+W+Washington+Chicago’. If
you are using the free API, append to this string ‘&key=‘. Place
that at the finish of the prefix ‘’
and child, you have obtained a stew going.

In Python, with address_str as ‘804+W+Washington+Chicago’ and key as
‘ThisI$_Yr_ap_iKEy’ (however, you recognize, truly your API key) this appears like:

prefix = ''
url = urlparse.urlparse('{0}?tackle={1}&key={2}'.format(prefix,
full_url = url.scheme + '://' + url.netloc + url.path + '?' + url.question

With a Work API account, that is fully extra sophisticated. Security requires
you generate a signature every time you ship a request, and that is carried out with
Base64 encoding and HMAC-SHA1 algorithm and different such nonsense that I do not
bear in mind anymore. But, the code under most likely nonetheless works (with address_str
the similar, and shopper=’YOUR CLIENT ID’ and private_key=’YOUR CRYPTO KEY’):

prefix = ''
url = urlparse.urlparse('{0}?tackle={1}&shopper={2}'.format(prefix,
url_to_sign = url.path + "?" + url.question
decoded_key = base64.urlsafe_b64decode(private_key)
signature =, url_to_sign, hashlib.sha1)
encoded_signature = base64.urlsafe_b64encode(signature.digest())
original_url = url.scheme + '://' + url.netloc + url.path + '?' + url.question
full_url = original_url + '&signature=' + encoded_signature

With full_url in hand, ship this as a request, interpret the JSON, and
you have obtained your geocode [lat, lng] Python 2-list!

req = urllib2.Request(full_url)
opener = urllib2.build_opener()
f =
d = simplejson.load(f)
geocode = [d['results'][0]['geometry']['location']['lat'],

Distance Matrix API

The Distance Matrix API is extra sophisticated solely in that it has extra
parameters which you can go to it and a way more sophisticated JSON return.
But, it offers the meat for the isochrone algorithm. The Distance Matrix
API returns a matrix of journey occasions and distances given a listing of origins
and locations, with every aspect of the matrix corresponding to at least one
origin-destination pair. To calculate isochrones, we’ll be using just one
origin (so that is extra of a Distance Vector, I assume), and the vacation spot
factors can be an set of factors organized symmetrically at totally different angles
round the origin (every a radius $r_i$ away from the origin that varies as
we traverse by the algorithm).

In normal, the Distance Matrix API takes origins and locations as
both tackle strings (as written earlier than), with teams concatenated with a
| image (e.g. ‘origins=Address+1|Address+2&locations=41.88,-87.62|Address+3’).
In our case, we have now just one origin and a set of locations which can be chosen
for us in the algorithm later. So, I will not hassle with developing these strings
explicitly right here. You can even go it a number of non-obligatory parameters, which I’ve
hard-coded in (however you may change, in case you’re so inclined — I made ‘mode=strolling’
for the pattern at the begin, for instance). Otherwise, all the steps above for
constructing a correct URL to go are the similar.

The JSON output is in the type of a matrix, with ‘rows’
equivalent to origins and ‘parts’ equivalent to locations.
To parse our JSON, we’ll have only one row and a number of parts. Our
‘parse_json’ perform will then take a URL as enter, ship it as a request,
learn the JSON return, and return a listing of lists of the kind [addresses,
durations], with durations being in minutes:

def parse_json(url=''):
    req = urllib2.Request(url)
    opener = urllib2.build_opener()
    f =
    d = simplejson.load(f)
    i = 0
    durations = [0] * len(addresses)
    for row in d['rows'][0]['elements']:
        if 'duration_in_traffic' in row:
            durations[i] = row['duration_in_traffic']['value'] / 60
            durations[i] = row['duration']['value'] / 60
        i += 1
    return [addresses, durations]

Selecting Destinations and the Evils of Spherical Geometry

Given an origin tackle (which is translated right into a [lat, lng] pair
by the geocode tackle perform), we have to choose a collection of vacation spot
addresses which can be chosen by discovering $n$ factors distributed symmetrically
(in angle) round the origin level. For every vacation spot level round the
origin (which is outlined by a radius $r_i$ and bearing $b_i$), we have to
calculate the corresponding [$lat_i$, $lng_i$]. This is not so simple as using
the Pythagorean theorem in Cartesian house as a result of we’re on a sphere (contemplate
that the distance in miles between two factors of longitude in Florida is
significantly totally different than it’s in Canada). We have to make use of these sophisticated
Haversine issues. Using $R$= 3,963 miles (the radius of the Earth) and
changing the origin [lat, lng] and the bearing $b_i$ into radians, the
latitude of the vacation spot is:

$mathrm{lat}_i = mathrm{asin}left[sin(mathrm{lat}) cos(r_i / R) + cos(mathrm{lat}) sin(r_i / R) cos(b_i)right]$

and the longitude is:

$mathrm{lng}_i = mathrm{lng} + mathrm{atan2}left[sin(b_i) sin(r_i / R) cos(mathrm{lat}), cos(r_i / R) – sin(mathrm{lat}) sin(mathrm{lat}_i)right]$

In python, this appears like (with ‘r’ taking part in the position of the radius of Earth, and
‘radius’ and ‘bearing’ equivalent to the vacation spot):

from math import cos, sin, tan, sqrt, pi, radians, levels, asin, atan2

r = 3963.1676
bearing = radians(angle)
lat1 = radians(origin_geocode[0])
lng1 = radians(origin_geocode[1])
lat2 = asin(sin(lat1) * cos(radius / r) + cos(lat1) * sin(radius / r) * cos(bearing))
lng2 = lng1 + atan2(sin(bearing) * sin(radius / r) * cos(lat1), cos(radius / r) - sin(lat1) * sin(lat2))
lat2 = levels(lat2)
lng2 = levels(lng2)

Finally, Calculating Isochrones

At lengthy final, we have constructed up the equipment to proceed. We have an origin tackle
which we have geocoded into [lat, lng]. We have a quantity $n$ of bearing angles
bibi that we will calculate the vacation spot [$lat_i$, $lng_i$] pairs for, given a
specific $r_i$. The crux of our isochrone builder is then to carry out
one thing like a binary search in radius alongside every bearing angle. The fantastic thing about
the Distance Matrix API is that it permits us to carry out one search alongside every
bearing angle with just one API name (so long as we keep inside output
measurement limits, e.g. 100 parts per question). This enormously reduces our API
request load and permits us to remain inside price range.

The Algorithm

The algorithm is as follows:

  1. Start with an preliminary radius guess ‘rad1’ which is a listing of size $n$, every aspect
    being one thing like ‘period’ / 12 (the place ‘period’ corresponds to the minute-size
    of the isochrone).

  2. For every angle symmetrically distributed round the origin (saved in listing
    ‘phi1’), calculate the vacation spot [latii, lngii] pair using the technique described
    above. Store these in a listing of 2-lists referred to as ‘iso’ — this can be your closing
    output isochrone, ultimately. It will look one thing like [[$lat_0$, $lng_0$],
    [$lat_1$, $lng_1$], …].

  3. Create a URL using the origin tackle or geocode and vacation spot
    [$lat_i$, $lng_i$] pairs saved in ‘iso’ and go this to the Distance Matrix API.
    Parse the JSON and return the durations to every level.

  4. For every level $i$, if the API-returned period is bigger than the
    desired isochrone ‘period’ (genuinely, past ‘period’ plus some
    ‘tolerance’ — the returned period ought to by no means actually precisely equal
    what we would like), set the $i$th part of ‘rad1’ to the imply of what it simply
    was and the smallest its ever been in the search (or Zero if it is by no means been
    smaller than it’s now). If the API-returned period is lower than the
    desired isochrone ‘period’ (minus some ‘tolerance’), set the $i$th part
    of ‘rad1’ to the imply of what it simply was and the largest its ever been in the
    search (or one thing large however not too large).

  5. If the API-returned period for the $i$th part is inside some
    ‘tolerance’ of the isochrone ‘period’, simply depart it alone this time.

  6. Continue this till no parts of ‘rad1’ change or we have now churned too lengthy
    (in observe, at all times be certain that your whereas loops do not go on into infinity!).

# Make a radius listing, one aspect for every angle, whose parts will replace till the isochrone is discovered
rad1 = [duration / 12] * number_of_angles  # preliminary r guess primarily based on 5 mph pace
phi1 = [i * (360 / number_of_angles) for i in range(number_of_angles)]
data0 = [0] * number_of_angles
rad0 = [0] * number_of_angles
rmin = [0] * number_of_angles
rmax = [1.25 * duration] * number_of_angles  # rmax primarily based on 75 mph pace
iso = [[0, 0]] * number_of_angles

# Counter to make sure we're not getting out of hand
j = 0

# Here's the place the binary search begins
whereas sum([a - b for a, b in zip(rad0, rad1)]) != 0:
    rad2 = [0] * number_of_angles
    for i in vary(number_of_angles):
        iso[i] = select_destination(origin, phi1[i], rad1[i], access_type, config_path)
    url = build_url(origin, iso, access_type, config_path)
    information = parse_json(url)
    for i in vary(number_of_angles):
        if (information[1][i] < (period - tolerance)) & (data0[i] != information[0][i]):
            rad2[i] = (rmax[i] + rad1[i]) / 2
            rmin[i] = rad1[i]
        elif (information[1][i] > (period + tolerance)) & (data0[i] != information[0][i]):
            rad2[i] = (rmin[i] + rad1[i]) / 2
            rmax[i] = rad1[i]
            rad2[i] = rad1[i]
        data0[i] = information[0][i]
    rad0 = rad1
    rad1 = rad2
    j += 1
    if j > 30:
        elevate Exception("This is taking too long, so I'm just going to quit."

A Beautiful Example

Want to know what a (traffic-less) set of isochrones appears like round the Sears Tower? Behold: 5-, 10-, and 15-minute isochrones.

[Note: this is not without erroneous data. I had to go in there and remove a point that somehow ended up in Los Angeles. There are, of course, ways to throw out outliers. That’s left as an exercise to the reader.]

Notice how the isochrones aren’t common shapes? They observe the interstate construction and the grid construction primarily, as they need to. I believe that’s simply so freakin’ cool.

I hope you discovered this as cool as I did.

Again, yow will discover my code for this on my github web page, module identify is isocronut.


Source hyperlink

Write a comment