Replacing Distance Matrix with Directions API

In Directions API, at a minimum, you pass in an “origin” location and a “destination” location. That is the equivalent of doing a 1-by-1 Distance Matrix call. In the response, you’ll get:

• an array of “routes” (the best route first, with additional alternate routes if applicable)
• each route is composed of an array of “legs” (a simple origin-to-destination route will have only 1 leg)

The legs are what you’re interested in. The leg object is where the “distance” and “duration” properties reside (similar to what you’d get from Distance Matrix). Here is a simplified view of that structure (there are many other properties, but this is what you’re after to get just the drive time & distance):

{
   "routes": [
      {
         "legs": [
            {
               "distance": {
                  "value": 1609,
                  "text": "1 mi"
               },
               "duration": {
                  "value": 600,
                  "text": "10 min"
               }
            }
         ]
      }
   ]
}

Waypoints to the rescue

Now, the potential savings of Directions vs. Distance Matrix come in with the “waypoints” parameter. Waypoints are the stops you make along the way between your origin and destination (e.g. stopping at the grocery store along my commute home would be a waypoint between my work origin and home destination). Waypoints split a route into multiple “legs” and, as shown above, each leg has its own distance and duration.  More on waypoints here: https://developers.google.com/maps/documentation/directions/intro#Waypoints

By carefully structuring the manner in which you insert appointments as waypoints on a Directions API route, you can potentially combine what are currently multiple Distance Matrix calls into a single Directions call.  A single Directions request (up to 9 waypoint) costs the same as only a single Distance Matrix element.  A single Directions Advanced request (from 10-23 waypoints) is the same cost as a mere two Distance Matrix elements.  See the Maps Platform pricing sheet for details.

Illustration

To illustrate the approach, let’s imagine a day where a technician has 3 appointments (we’ll call them A, B, C), and they start and end their day at home…

Appointment to appointment

This request has the technician starting at home, then stopping at appointments A,B,C in order, and finally ending back at home.

.../directions/json?origin={HOME}&waypoints={A}|{B}|{C}&destination={HOME}&key=...

This route would contain 4 legs:  

1. HOME to A
2. A to B
3. B to C
4. C to HOME

The equivalent Distance Matrix request(s) would require 4 elements, but instead this only costs 1 Directions request (the equivalent cost of 1 Distance Matrix element).

Home to each appointment

Instead of getting the distance between each appointment, if I wanted the distance from the technicians home to each appointment, I can structure my request like this:

.../directions/json?origin={HOME}&waypoints={A}|{HOME}|{B}|{HOME}|&destination={C}&key=...

This route would contain 5 legs:  

1. HOME to A  
2. A to HOME  
3. HOME to B  
4. B to HOME  
5. HOME to C

By inserting HOME waypoints between the appointments locations, I’ve constructed a route which will give me home-to-appointment distances/durations if I toss out legs 2 and 4 (legs 1, 3 , and 5 are all from home to an appointment).  The equivalent Distance Matrix request(s) would require 3 elements, but still this only costs 1 Directions request (the equivalent cost of 1 Distance Matrix element).