Location Classes
What if we want to find the distance and travel times between locations when we know where we're starting and going, but also where we need the locations to match in some way? In this case, we'll make use of the location_class parameter.
Let's consider the exaggerated real-world example started in the Sources and Destinations example. In that example, we had the current locations for a fleet of three (3) vehicles and locations of three (3) available fueling stations. In this example, we'll add the twist that each vehicle takes a particular type of fuel, and only certain fueling location offers this kind of fuel. We start by assigning an arbitrary class number to each fuel type:
| Fuel Type | Class |
|---|---|
| Gas | 0 |
| Diesel | 1 |
| Electric | 2 |
To frame the problem further, below is our fleet and fueling locations each with their designated location class:
| Fleet (location class) | Fueling Locations (location class) |
|---|---|
vehicle-gas (0) | fueling-gas (0) |
vehicle-diesel (1) | fueling-gas+diesel (0 and 1) |
vehicle-electric (2) | fueling-electric (2) |
Let's imagine this problem as a distance matrix. Obviously, we're only interested in the distances from vehicles to fueling locations where the fuel types match, 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)
- Vehicles to fueling locations without the correct fuel — we'd be stranded at a gas station if we needed diesel
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. There is also a new location_class which indicates the arbitrary class designation based on the type of fuel needed. 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.
| index | 0 | 1 | 2 | 3 | 4 | 5 | |||
|---|---|---|---|---|---|---|---|---|---|
| location class | 0 | 1 | 2 | 0 | [0, 1] | 2 | |||
| destinations | vehicle-gas | vehicle-diesel | vehicle-electric | fueling-gas | fueling-gas+diesel | fueling-electric | |||
| sources | |||||||||
| 0 | 0 | vehicle-gas | -- | -- | -- | YES | YES | -- | |
| 1 | 1 | vehicle-diesel | -- | -- | -- | -- | YES | -- | |
| 2 | 2 | vehicle-electric | -- | -- | -- | -- | -- | YES | |
| 3 | 0 | fueling-gas | -- | -- | -- | -- | -- | -- | |
| 4 | [0, 1] | fueling-gas+diesel | -- | -- | -- | -- | -- | -- | |
| 5 | 2 | fueling-electric | -- | -- | -- | -- | -- | -- |
In order to limit our distance matrix request so that it mirrors our template above and only returns relevant distances, we specify the sources, destinations, and location_class parameters using the indices and classes of each entry.
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 where one of the location_class is included:
vehicle-gastofueling-gasandfueling-gas+dieselvehicle-dieseltofueling-gas+dieselvehicle-electrictofueling-electric