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
`vehicle-1``fueling-1`
`vehicle-2``fueling-2`
`vehicle-3``fueling-3`

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.

index012345
destinations`vehicle-1``vehicle-2``vehicle-3``fueling-1``fueling-2``fueling-3`
sources
0`vehicle-1`------YESYESYES
1`vehicle-2`------YESYESYES
2`vehicle-3`------YESYESYES
3`fueling-1`------------
4`fueling-2`------------
5`fueling-3`------------

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