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
Let’s consider an exaggerated real-world example to clarify the use of
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:
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
destinations parameters using the index of each entry. For this example then, our
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: