Posted by Corey Bradford, Google Maps Solution Architect

Editor’s note: ‘Map Tips’ are designed to answer frequently asked questions about Google Maps APIs. For important tips on how to deploy Google’s mapping tools, read more from Corey Bradford, Google Maps Solution Architect at Google.

Many location-based sites and applications can accurately tell users how far they are from nearby points of interest. However, they often provide only straight-line distance (ie as the crow flies), which isn’t always a true representation of proximity. Alternatively, these applications can be improved by the Distance Matrix service available in the Google Maps Javascript API and the Distance Matrix Web Service, which provides accurate travel distances and times, and for premium customer can even factor in current traffic conditions.

Store locators and rideshare/taxi applications are common applications that can benefit from using the Distance Matrix service. In both use cases, a user is trying to determine their relative distance from either a store or taxi.

Store locators
Suppose a customer has provided their location, “1903 Toro Canyon Rd, Austin, TX 78746.” (Point C on the map) Using straight-line distances, your application found your three nearest stores, as shown on this map:
“As the crow flies,” store #1 (shown in the image below as "B") is clearly nearest to the customer location, “C.” However, there’s a river between these locations. Unless the customer intends to use watercraft for part of their travel, they’ll need to travel via the nearest bridge or tunnel. The Directions Service provides the suggested route, confirming the need to travel much farther than the straight-line distance:

Since we know that the straight-line distance doesn’t accurately reflect the proximity of the stores in this case, let’s make a call to the Distance Matrix Service to determine actual driving distances and times. Here are the results returned:



Now we have some useful information for the customer. First, we can see that, although store #2 is the farthest in a straight line, it’s actually the shortest driving distance. In addition, in normal traffic conditions, it’s also the shortest driving time. However, if we consider current traffic conditions, we see that store #2 will take longer to reach than store #3. The following maps, which use the Directions Service along with the traffic layer, illustrate these results:

In this case, the customer may choose to visit store #3 (shown in the image below as "B") if they are leaving now or store # 2 if they plan to travel later, after traffic clears.

Rideshare and taxis
Now let’s consider another example: users looking to hire a car service or dispatchers who need to direct the nearest taxi to a customer. As the following maps shows, the user can see the actual current drive times, provided by the Distance Matrix API, of each driver to their location, regardless of straight-line distance.

What's Under The Hood
Now that we’re taken a look at how driving distances, duration, and duration in traffic information can benefit your customers, you might be wondering “How can I implement this as a developer?” Below are code snippets from the store locator example that provide the technical details of how to build these features using the Distance Matrix service.

For simplicity, we’ve pre-defined the customer and store locations:

var customerLocation = '1903 Toro Canyon Rd, Austin, TX 78746';

var store1 = '3808 W. 35th, Austin, TX 78703';
var store2 = '4933 Plaza on the Lake, Austin, TX 78746';
var store3 = '6500 Bee Cave Rd, Austin, TX 78746';

Using this location information, we make a call to the Distance Matrix service:

function calculateDistances() {
  // Create a new Distance Matrix Service object
  var service = new google.maps.DistanceMatrixService();
  
  // Set the options such as the pre-defined origin
  // and destinations, as well as specifying to use
  // duration in traffic
  
  service.getDistanceMatrix({
      origins: [customerLocation],
      destinations: [store1, store2, store3],
      travelMode: google.maps.TravelMode.DRIVING,
      unitSystem: google.maps.UnitSystem.IMPERIAL,
      avoidHighways: false,
      avoidTolls: false,
      durationInTraffic: true
  }, callback);
} 
   
function callback(response, status) {
  if (status != google.maps.DistanceMatrixStatus.OK) {
    console.log('DistanceMatrix Error: ', status);
  } else {
    // Get the arrays of origins and destinations
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;
    
    for (var i = 0; i < origins.length; i++) {
      // For each of the origins, get the results of the 
      // distance and duration of the destinations
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
    // Store the results for later sorting
   storeResults.push([destinations[j],
       results[j].duration_in_traffic.value,
                  results[j].distance.value]);
      }
    }
    // Sort the results by duration in traffic
     storeResults.sort(function(a, b) {
           return a[1] - b[1];
         }); 
  }
}

The call returns the following data, which includes the critical information of driving distances, duration, and duration in traffic:

destination_addresses" : [
      "3808 West 35th Street, Austin, TX 78703, USA",
      "4933 Plaza on the Lake, Austin, TX 78746, USA",
      "6500 Bee Cave Road, Austin, TX 78746, USA"
   ],
   "origin_addresses" : [ "1903 Toro Canyon Road, Austin, TX 78746, USA" ],
   "rows" : [
      {
         "elements" : [
            {
               "distance" : {
                  "text" : "5.4 mi",
                  "value" : 8631
               },
               "duration" : {
                  "text" : "15 mins",
                  "value" : 917
               },
               "duration_in_traffic" : {
                  "text" : "20 mins",
                  "value" : 1188
               },
               "status" : "OK"
            },
            {
               "distance" : {
                  "text" : "4.4 mi",
                  "value" : 7157
               },
               "duration" : {
                  "text" : "9 mins",
                  "value" : 569
               },
               "duration_in_traffic" : {
                  "text" : "15 mins",
                  "value" : 911
               },
               "status" : "OK"
            },
            {
               "distance" : {
                  "text" : "4.7 mi",
                  "value" : 7490
               },
               "duration" : {
                  "text" : "11 mins",
                  "value" : 635
               },
               "duration_in_traffic" : {
                  "text" : "11 mins",
                  "value" : 635
               },
               "status" : "OK"
            }
         ]
      }

With this data, customers can sort the store results according to their preferences and make better decisions about which store to visit.

We hope you’re able to take advantage of some of these features in your website or application. For more details on implementing the Google Maps Javascript API Distance Matrix service, visit our developer documentation and review our available code samples. You can also find out more about the Distance Matrix API, part of our Google Maps Web Services APIs.