This is one stop global knowledge base where you can learn about all the products, solutions and support features.
The simplest example of using the distance matrix service is to apply no filters (
sources
and
destionations
are unused) and request a single traffic window (
"weekend": true
). This simple format will result in an all-versus-all distance matrix for a single traffic window. An example of input and output is provided below.
If you provide more than 200
locations
in a distance matrix requesst, the Optimization API will process the request asynchronously due to the computation time being longer than a connection timeout. As a result, the service will respond with a
jobid
and URI that can be used to retrieve the input using the
GET
method on the same endpoint. An example is shown below.
The meaning of "location classes with force containment" is requiring source location classes to be completely contained by the destination location classes. For example, if a skilled labor team has drywall and painting skills, we want that team to service job sites in need of drywall or painting skills, and not job sites in need of drywall, painting, AND electrical. The reason is obviously that a second team will have to cover the electrical work.
We abandon the vehicle-fueling station problem presented in the Sources and Destinations and Location Classes examples. Instead, let us consider three (3) teams of skilled technicians and six (6) job sites needing skilled labor. How would we submit a distance matrix to find which teams are closest to the job site most relevant to their skills? In this case, we'll make use of the
force_containment
parameter.
Our teams can have one or all of the following skills:
| Available Skills | Class |
|---|---|
| Painting |
0
|
| Drywall |
1
|
| Framing |
2
|
| Concrete |
3
|
| Electrical |
4
|
| Plumbing |
5
|
| HVAC |
6
|
To frame the problem further, listed below are our teams and their skills with associated classes for each:
| Team | Skills |
|---|---|
team-paint+concrete+hvac
|
paint (
0
), concrete (
3
), and hvac (
6
)
|
team-drywall+electrical
|
drywall (
1
) and electrical (
4
)
|
team-concrete+plumbing
|
framing (
2
) and plumbing (
5
)
|
Our job sites in this example are:
| Job Sites | Skill Needs |
|---|---|
jobsite-paint+hvac
|
paint (
0
) and hvac (
6
)
|
jobsite-paint+concrete+hvac
|
paint (
0
), concrete (
3
), hvac (
6
)
|
jobsite-drywall
|
drywall (
1
)
|
jobsite-drywall+electrical
|
drywall (
1
) and electrical (
4
)
|
jobsite-paint+framing+plumbing
|
paint (
0
), framing (
2
), plumbing (
5
)
|
jobsite-all
|
All |
Unlike the prior examples where we broke down the problem into visual examples, the number of combinations here is too large to visualize simply. This is where the power of our Distance Matrix service shines!
To handle this complexity, all you need to do is apply the same
location_class
parameters as in the other examples, but this time we will add the
force_containment
parameter to ensure that when a job site needs multiple skills,
ALL
of those skill needs are met.
The complete request we will send to the Distance Matrix endpoint is given below.
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 all of the destinations
location_class
needs are met. The results we get are:
team-concrete+plumbing
is not eligible for any job site because the only job site in need of concrete and plumbing work also needs all the other types of skilled work (HVAC, paint, etc.), which this team does not possess. Thus there are no
travel_costs
returned for them.
team-drywall+electrical
is eligible for the
jobsite-drywall
or
jobsite-drywall+electrical
because they are the only team which can handle both types of work.
team-paint+concrete+hvac
is eligible for two job sites —
jobsite-paint+concrete+hvac
and
jobsite-paint+hvac
— because they have the overlapping skills needed.
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:
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.
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-gas
to
fueling-gas
and
fueling-gas+diesel
vehicle-diesel
to
fueling-gas+diesel
vehicle-electric
to
fueling-electric
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:
| Fleet | Fueling 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:
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.
| index | 0 | 1 | 2 | 3 | 4 | 5 | ||
|---|---|---|---|---|---|---|---|---|
| destinations |
vehicle-1
|
vehicle-2
|
vehicle-3
|
fueling-1
|
fueling-2
|
fueling-3
|
||
| sources | ||||||||
| 0 |
vehicle-1
|
-- | -- | -- | YES | YES | YES | |
| 1 |
vehicle-2
|
-- | -- | -- | YES | YES | YES | |
| 2 |
vehicle-3
|
-- | -- | -- | YES | YES | YES | |
| 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.
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
Traffic windows refer to the time segments that have an effect on traffic costs. Obviously, heavy traffic will result in higher overall traffic costs.
The Optimization API returns all traffic windows by default. However, you can limit the size of the response by setting start and end times. With start and end times, the Optimization API will only return traffic windows which “touch” the start and end times. This example illustrates that use case.
Suppose you’re only interested in two-time windows that correspond to the morning commute. In this example, we set the start_local_time parameter to 9:00 am and the end_local_time parameter to 12:00.
In the response, the Optimization API has found two traffic windows (indexed 0 and 1) that intersect with these times. It uses this data to reduce the size of the matrix. You can review a sample traffic window below. Note that a single window consists of an index, a start time, and an end time. These windows are referenced by the travel cost object.
Note that the travel cost object refers to the actual matrix that the Optimization API calculates. It consists of the travel distance in meters and the travel cost for each window. The sample JSON provides comments to explain the output.