Get the Distance Matrix

The GetDistanceMatrix() Apex method takes a set of locations and returns the estimated travel distance and times between the locations.

Let’s say you have two locations A and B. This method returns matrices of travel distance and times between A-B and B-A. The diagonal elements of the matrices, A-A and B-B, are zero as the travel distance and time from one spot to the same spot are zero. The values for A-B and B-A can be different as the returning path isn’t always the same path. The travel times are calculated for different time windows so there’s a travel time matrix for each time window.

Signature

1Map<String, Object> maps.API.GetDistanceMatrix(List<Map<String, Object>>)

Where,

maps is the namespace that's available after you install Salesforce Maps.
API is the class that contains the global methods exposed to developers.
GetDistanceMatrix() is the method.

Allocations

Include as many as 20 locations. To catch exceptions, put a try-catch block around your code.

Sample Code

This code finds the estimated travel distance and time between two grocery stores.

1// Create a list of locations.
2List<Map<String, Object>> locations = 
3 new List<Map<String, Object>>(); 
4
5// Create and add location 1.
6Map<String, Object> groceryNorth = 
7 new Map<String, Object> { 
8 'location_id' => 'groceryNorth', 
9 'latitude' => 33.917760, 
10 'longitude' => -84.379750 
11};
12locations.add(groceryNorth); 
13
14// Create and add location 2.
15Map<String, Object> grocerySouth = 
16 new Map<String, Object> { 
17 'location_id' => 'grocerySouth', 
18 'latitude' => 33.840630, 
19 'longitude' => -84.381920 
20}; 
21locations.add(grocerySouth);
22 
23// Call the GetDistanceMatrix() method with the list of locations.
24Map<String, Object> matrix = maps.API.GetDistanceMatrix(locations); 
25
26// Log the resulting distance matrix.
27system.debug(matrix);

Sample Response

Although the return value is an Apex Map<String, Object> object, this JSON response illustrates the essential data you receive in the resulting map.

1{
2  "endPoint": "https://internal.na.sfmapsapi.com/core/routing/matrix/1",
3  "limitInfo": {
4    "QueryRows": "12 / 50000",
5    "Queries": "8 / 100",
6    "HeapSize": "73745 / 6000000",
7    "CPUTime": "150 / 10000"
8  },
9  "request": "{\"vehicle\":{\"type\":\"car\"},\"locations\":[{\"longitude\":-84.379750,\"latitude\":33.917760,\"location_id\":\"groceryNorth\"},{\"longitude\":-84.381920,\"latitude\":33.840630,\"location_id\":\"grocerySouth\"}]}",
10  "params": {
11    "locations": [
12      {
13        "location_id": "groceryNorth",
14        "latitude": 33.91776,
15        "longitude": -84.37975
16      },
17      {
18        "location_id": "grocerySouth",
19        "latitude": 33.84063,
20        "longitude": -84.38192
21      }
22    ],
23    "vehicle": {
24      "type": "car"
25    }
26  },
27  "success": true,
28  "data": {
29    "Solution": {
30      "travel_costs": {
31        "grocerySouth": { 
32          "grocerySouth": [ // The values of the matrix diagonals are zero because the distance and time between grocerySouth and grocerySouth are zero.
33            0, // Matrix 0 index 0: Travel distance
34            0, // Matrix 1 index 0: Travel time for time window 0
35            0, // Matrix 2 index 0: Travel time for time window 1
36            0, // And so forth...
37            0,
38            0,
39            0,
40            0,
41            0
42          ],
43          "groceryNorth": [ // The values for grocerySouth to groceryNorth.
44            9210,  // Matrix 0 index 1: Travel distance
45            794.6, // Matrix 1 index 1: Travel time for time window 0
46            810.5, // Matrix 2 index 1: Travel time for time window 1
47            890, // And so forth...
48            920.7,
49            965.7,
50            1047.2,
51            1048.8,
52            952.5
53          ]
54        },
55        "groceryNorth": {
56          "grocerySouth": [ // The values for groceryNorth to grocerySouth.
57            9274.1, // Matrix 0 index 2: Travel distance
58            797.9, // Matrix 1 index 2: Travel time for time window 0
59            808.3, // Matrix 2 index 2: Travel time for time window 1
60            879, // And so forth...
61            905.3,
62            944.2,
63            974.6,
64            963.5,
65            920.5
66          ],
67          "groceryNorth": [  // The values for the matrix diagonals are zero.
68            0, // Matrix 0 index 3: Distance
69            0, // Matrix 1 index 3: Time for time window 0
70            0, // Matrix 2 index 3: Time for time window 1
71            0, // And so forth...
72            0,
73            0,
74            0,
75            0,
76            0
77          ]
78        }
79      },
80      "traffic_windows": [
81        { // Time window for matrix 1: midnight to 6:30 am and 7 pm to midnight.
82          "traffic_window_start_times": [
83            "00:00:00",
84            "19:00:00"
85          ],
86          "traffic_window_index": 0,
87          "traffic_window_end_times": [
88            "06:30:00",
89            "00:00:00"
90          ]
91        },
92        { // Time window for matrix 2: 6:30 am to 7:30 am.
93          "traffic_window_start_times": [
94            "06:30:00"
95          ],
96          "traffic_window_index": 1,
97          "traffic_window_end_times": [
98            "07:30:00"
99          ]
100        },
101        { // And so forth...
102          "traffic_window_start_times": [
103            "07:30:00"
104          ],
105          "traffic_window_index": 2,
106          "traffic_window_end_times": [
107            "08:30:00"
108          ]
109        },
110        {
111          "traffic_window_start_times": [
112            "08:30:00"
113          ],
114          "traffic_window_index": 3,
115          "traffic_window_end_times": [
116            "09:30:00"
117          ]
118        },
119        {
120          "traffic_window_start_times": [
121            "09:30:00"
122          ],
123          "traffic_window_index": 4,
124          "traffic_window_end_times": [
125            "16:00:00"
126          ]
127        },
128        {
129          "traffic_window_start_times": [
130            "16:00:00"
131          ],
132          "traffic_window_index": 5,
133          "traffic_window_end_times": [
134            "17:00:00"
135          ]
136        },
137        {
138          "traffic_window_start_times": [
139            "17:00:00"
140          ],
141          "traffic_window_index": 6,
142          "traffic_window_end_times": [
143            "18:00:00"
144          ]
145        },
146        {
147          "traffic_window_start_times": [
148            "18:00:00"
149          ],
150          "traffic_window_index": 7,
151          "traffic_window_end_times": [
152            "19:00:00"
153          ]
154        }
155      ],
156      "status": "Ok",
157      "locations": [
158        {
159          "time_zone": "America/New_York", // Time zone of the location.
160          "location_id": "groceryNorth"
161        },
162        {
163          "time_zone": "America/New_York",
164          "location_id": "grocerySouth"
165        }
166      ]
167    },
168    "JobStatus": "Completed",
169    "JobMessage": {
170      "comment": "MARE job succeeded"
171    },
172    "JobId": "mare-matrix-11-1619788548.552854-151"
173  }
174}

Salesforce Maps Developer Guide

Get the Distance Matrix

Signature

Allocations

Sample Code

Sample Response