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 a fleet of three (3) vehicles and three (3) available fueling locations. 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-1fueling-1
vehicle-2fueling-2
vehicle-3fueling-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
destinationsvehicle-1vehicle-2vehicle-3fueling-1fueling-2fueling-3
sources
0vehicle-1YESYESYES
1vehicle-2YESYESYES
2vehicle-3YESYESYES
3fueling-1
4fueling-2
5fueling-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:

"sources": [0, 1, 2]
"destinations": [3, 4, 5]

Sample Request

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

{
    "sources": [0, 1, 2],
    "destinations": [3, 4, 5],
    "vehicle": {
        "type": "car"
    },
    "locations": [
        {
            "location_id": "vehicle-1",
            "latitude": 33.937244,
            "longitude": -84.36947
        },
        {
            "location_id": "vehicle-2",
            "latitude": 33.8875767,
            "longitude": -84.2613857
        },
        {
            "location_id": "vehicle-3",
            "latitude": 33.8875767,
            "longitude": -84.2613857
        },
        {
            "location_id": "fueling-1",
            "latitude": 33.8968108,
            "longitude": -84.3276536
        },
        {
            "location_id": "fueling-2",
            "latitude": 33.8730743,
            "longitude": -84.3951042
        },
        {
            "location_id": "fueling-3",
            "latitude": 33.8940743,
            "longitude": -84.2151042
        }
    ]
}

Sample Response

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 tofueling-1/2/3
  • vehicle-3 to fueling-1/2/3
{
    "locations": [
        {
            "location_id": "vehicle-1",
            "time_zone": "America/New_York"
        },
        {
            "location_id": "vehicle-2",
            "time_zone": "America/New_York"
        },
        {
            "location_id": "vehicle-3",
            "time_zone": "America/New_York"
        },
        {
            "location_id": "fueling-1",
            "time_zone": "America/New_York"
        },
        {
            "location_id": "fueling-2",
            "time_zone": "America/New_York"
        },
        {
            "location_id": "fueling-3",
            "time_zone": "America/New_York"
        }
    ],
    "status": "Ok",
    "traffic_windows": [
        {
            "traffic_window_end_times": [
                "06:30:00",
                "00:00:00"
            ],
            "traffic_window_index": 0,
            "traffic_window_start_times": [
                "00:00:00",
                "19:00:00"
            ]
        },
        {
            "traffic_window_end_times": [
                "07:30:00"
            ],
            "traffic_window_index": 1,
            "traffic_window_start_times": [
                "06:30:00"
            ]
        },
        {
            "traffic_window_end_times": [
                "08:30:00"
            ],
            "traffic_window_index": 2,
            "traffic_window_start_times": [
                "07:30:00"
            ]
        },
        {
            "traffic_window_end_times": [
                "09:30:00"
            ],
            "traffic_window_index": 3,
            "traffic_window_start_times": [
                "08:30:00"
            ]
        },
        {
            "traffic_window_end_times": [
                "16:00:00"
            ],
            "traffic_window_index": 4,
            "traffic_window_start_times": [
                "09:30:00"
            ]
        },
        {
            "traffic_window_end_times": [
                "17:00:00"
            ],
            "traffic_window_index": 5,
            "traffic_window_start_times": [
                "16:00:00"
            ]
        },
        {
            "traffic_window_end_times": [
                "18:00:00"
            ],
            "traffic_window_index": 6,
            "traffic_window_start_times": [
                "17:00:00"
            ]
        },
        {
            "traffic_window_end_times": [
                "19:00:00"
            ],
            "traffic_window_index": 7,
            "traffic_window_start_times": [
                "18:00:00"
            ]
        }
    ],
    "travel_costs": {
        "vehicle-1": {
            "fueling-1": [
                9132.2,
                620.8,
                712.2,
                845.3,
                805.1,
                788.6,
                1046.4,
                1075.7,
                912
            ],
            "fueling-2": [
                9002.9,
                760.8,
                746,
                831.9,
                887.3,
                922.6,
                1006.7,
                1008.5,
                949.5
            ],
            "fueling-3": [
                20780.5,
                1219.5,
                1275.1,
                1397.9,
                1369.7,
                1533.8,
                2496.1,
                2621.3,
                2150.6
            ]
        },
        "vehicle-2": {
            "fueling-1": [
                8354.6,
                725.1,
                748.9,
                846.4,
                868.9,
                864.7,
                881.9,
                879.3,
                869.9
            ],
            "fueling-2": [
                20019.3,
                1187.1,
                1349.8,
                1638,
                1579,
                1383.8,
                1473.5,
                1484.9,
                1427.1
            ],
            "fueling-3": [
                7212.6,
                658.3,
                623.5,
                670.7,
                697.3,
                739.3,
                807.3,
                828.1,
                835.1
            ]
        },
        "vehicle-3": {
            "fueling-1": [
                8354.6,
                725.1,
                748.9,
                846.4,
                868.9,
                864.7,
                881.9,
                879.3,
                869.9
            ],
            "fueling-2": [
                20019.3,
                1187.1,
                1349.8,
                1638,
                1579,
                1383.8,
                1473.5,
                1484.9,
                1427.1
            ],
            "fueling-3": [
                7212.6,
                658.3,
                623.5,
                670.7,
                697.3,
                739.3,
                807.3,
                828.1,
                835.1
            ]
        }
    }
}