Sources and Destinations

What if we want to find the distance and travel times between locations when we know where we're starting and going? In this case, we'd make use of the sources and destinations parameters.

Let’s consider an exaggerated real-world example to clarify the use of sources and destinations. Suppose we have the current locations for a fleet of three (3) vehicles and the locations of three (3) available fueling stations. The sources (where we are coming from) and destinations (where we are going to) parameters limit the size of the returned matrix to only the desired results. This makes post-processing by your code simpler because you can apply filters (a parallelized operation) to what are sometimes large, complex matrices.

To frame the problem, below is our fleet and fueling locations:

FleetFueling Locations

Let's imagine this problem as a distance matrix. Obviously, we're only interested in the distances from vehicles to fueling locations, and not interested in the distances for:

  • A vehicle or fueling location to itself — where would it get fuel?
  • Vehicles to other vehicles — other vehicles don't have fuel to share
  • Fueling locations to other fueling locations — other stations don't have fuel to share
  • Fueling locations to vehicles — the station cannot go to the vehicle (although that would be cool)

In the distance matrix template below, we've added a helpful zero-based "index" as a visual guide which is not part of the actual distance matrix inputs. Note that as a result of using an index-based approach, ORDER MATTERS. This is not an ideal design and is being updated in the next major revision of the API.


In order to limit our distance matrix request so that it mirrors our template above and only returns relevant distances, we specify the sources and destinations parameters using the index of each entry. For this example then, our sources and destinations parameters will look like this in the request:

The complete request we will send to the Distance Matrix endpoint is given below.

Expand to view request sample

The complete response we receive from the Distance Matrix endpoint is given below. As expected, we only have travel_costs which show going from sources to destinations:

  • vehicle-1 to fueling-1/2/3
  • vehicle-2 to fueling-1/2/3
  • vehicle-3 to fueling-1/2/3
Expand to view response sample