Travel cost matrix

Travel cost matrix example

A travel cost matrix between five major cities in Australia. Each row in the table represents the driving time in minutes and the driving distance in kilometers between a city pair.

What is a travel cost matrix?

A travel cost matrix, also known as the origin-destination (OD) cost matrix, is a table or a matrix containing the cost, such as the travel time or travel distance, from multiple origins to multiple destinations. It ranks the destinations that each origin connects to in ascending order based on the minimum cost required to travel from that origin to each destination.

You can use a travel cost matrix to build applications that:

  • Determine the accessibility of real estate by measuring the driving or walking time from the property to various nearby attractions.
  • Predict the travel behavior of people in a city by calculating the distances people would need to travel to reach certain attractions.
  • Calculate the shipping costs between postal codes using the travel distances from the cost matrix.
  • Use the travel cost matrix as an input in other mathematical models, for example, linear programming, that can be used to make better decisions.

How a travel cost matrix works

The typical workflow for generating a travel cost matrix is to define:

  1. Starting locations from which to travel to the destinations.
  2. Ending locations to travel to from the origins.
  3. The type of travel for the analysis.
  4. Call the service to find the travel cost matrix between origins and destinations.

URL requests

You can create travel cost matrix by making an HTTPS request to the origin-destination cost matrix service solveODCostMatrix operation or by using client APIs. Specify one or more origins and destinations, and optionally, additional parameters to refine the operation. Some of the most common parameters are described below.

Required parameters

NameDescriptionExamples
fThe format of the data returned.f=json f=pjson
tokenAn API key or OAuth 2.0 access token.token=<ACCESS_TOKEN>

Direct

Use for shorter transactions with up to 10 origins and 10 destinations that will complete in less than 5 minutes.

Use dark colors for code blocksCopy
1
https://route-api.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/NAServer/OriginDestinationCostMatrix_World/solveODCostMatrix?<parameters>
Use dark colors for code blocksCopy
1
https://route.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/NAServer/OriginDestinationCostMatrix_World/solveODCostMatrix?<parameters>

Key parameters

Name (Direct)DescriptionExamples
originsStarting locations from which to travel to the destinations.origins=-118.245843,34.057794;-117.16274,32.719178
destinationsEnding locations to travel to from the origins.destinations=-117.182676,34.055909;-118.144184,34.147832
travelModeThe mode of transportation such as driving a car or a truck or walking.travelMode=JSON Object
defaultTargetDestinationCountThe number of destinations to find per origin. A null value or no value for this parameter results in a search for all destinations from every origin.defaultTargetDestinationCount=null
defaultTargetDestinationCount=3
defaultCutoffThe travel time or travel distance value at which to stop searching for destinations from a given origin. The default value is null which means to search until all destinations are found for every origin. The units are time or distance based depending on your travel mode.defaultCutoff=5

Additional parameters: Set additional constraints when creating the travel cost matrix such as timeOfDay to use live traffic conditions or outputType to specify if the output is a table or a matrix representing travel costs.

Job

Use for longer transactions with up to 1,000 origins and 1,000 destinations that will complete in less than 60 minutes.

Use dark colors for code blocksCopy
1
https://logistics.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/GPServer/GenerateOriginDestinationCostMatrix/submitJob?<parameters>

Key parameters

Name (Direct)DescriptionExamples
originsStarting locations from which to travel to the destinations.origins={"features":[{"geometry":{"x":-118.245843,"y":34.057794}},{"geometry":{"x":-117.16274,"y":32.719178}}]}
destinationsEnding locations to travel to from the origins.destinations={"features":[{"geometry":{"x":-117.182676,"y":34.055909}},{"geometry":{"x":-118.144184,"y":34.147832}}]}
travel_modeThe mode of transportation such as driving a car or a truck or walking.travel_mode=JSON Object
number_of_destinations_to_findThe number of destinations to find per origin. A null value or no value for this parameter results in a search for all destinations from every origin.number_of_destinations_to_find=null
number_of_destinations_to_find=3
cutoffThe travel time or travel distance value at which to stop searching for destinations from a given origin. The default value is null which means to search until all destinations are found for every origin. The units are time or distance based depending on your travel mode.cutoff=5

Additional parameters: Set additional constraints when creating the travel cost matrix such as time_of_day to use live traffic conditions or output_format to specify if the output is a table or a file in CSV or GeoJSON format.

Code examples

Direct: Create time-distance matrix

In this example, the travel cost matrix service is used to find the travel time and travel distance between five major cities in Australia. Such a matrix can be used to calculate the cost of shipping goods between these cities by using the travel time and travel distance between any city pair.

To create the travel cost matrix, you need to provide the origins and destinations. In this example, the origins and destinations are identical, but they can be different. By default, the output matrix contains a system-generated identifier to represent each origin and destination. If you need to use your own identifier, you must pass this identifier as the ObjectID field when specifying the inputs.

The response contains odCostMatrix that contains an array of travel costs in minutes, miles, and kilometers between each origin ID and all the destination IDs. The order of the travel costs are based on the costAttributeNames.

APIs

ArcGIS API for Python
Expand
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
    # Connect to the origin destination cost matrix service and call it
    api_key = "YOUR_ACCESS_TOKEN"
    portal = arcgis.GIS("https://www.arcgis.com", api_key=api_key)
    od_cost_matrix = arcgis.network.ODCostMatrixLayer(portal.properties.helperServices.odCostMatrix.url,
                                                      gis=portal)
    result = od_cost_matrix.solve_od_cost_matrix(origins=cities,
                                                 destinations=cities,
                                                 )
    print_result(result)

REST API

cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
5
curl https://route-api.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/NAServer/OriginDestinationCostMatrix_World/solveODCostMatrix? \
-d "f=json" \
-d "token=<ACCESS_TOKEN>" \
-d "origins={'spatialReference':{'wkid':4326},'features':[{'geometry':{'x':153.03660,'y':-27.486320},'attributes':{'ObjectID':101}},{'geometry':{'x':144.983120,'y':-37.817870},'attributes':{'ObjectID':102}},{'geometry':{'x':151.223490,'y':-33.891220},'attributes':{'ObjectID':103}},{'geometry':{'x':149.133490,'y':-35.316850},'attributes':{'ObjectID':104}},{'geometry':{'x':138.596810,'y':-34.917470},'attributes':{'ObjectID':105}}]}" \
-d "destinations={'spatialReference':{'wkid':4326},'features':[{'geometry':{'x':153.03660,'y':-27.486320},'attributes':{'ObjectID':101}},{'geometry':{'x':144.983120,'y':-37.817870},'attributes':{'ObjectID':102}},{'geometry':{'x':151.223490,'y':-33.891220},'attributes':{'ObjectID':103}},{'geometry':{'x':149.133490,'y':-35.316850},'attributes':{'ObjectID':104}},{'geometry':{'x':138.596810,'y':-34.917470},'attributes':{'ObjectID':105}}]}"

Job: Calculate walkability

In this example, the walkability is calculated for the location of real estate property to basic amenities such as ATMs, restaurants, grocery stores, and parks. To determine walkability, you need to first find the walking distance (travel distance) to all of the amenities from the property location using the travel cost matrix service. Once you have all of the travel distances between the property location and the amenities, you can use them in a mathematical formula (such as a weighted mean) to calculate walkability.

You specify the property location as origins and the amenities as destinations. The default travel_mode is driving time, so in this case the travel mode is set to walking distance.

APIs

ArcGIS API for Python
Expand
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
    # Connect to the travel cost matrix service
    api_key = "YOUR_ACCESS_TOKEN"

    # Get the walking distance travel mode defined for the portal. Fail if the travel mode is not found.
    walking_distance_travel_mode = ""
    for feature in arcgis.network.analysis.get_travel_modes().supported_travel_modes.features:
        attributes = feature.attributes
        if attributes["AltName"] == "Walking Distance":
            walking_distance_travel_mode = attributes["TravelMode"]
            break
    assert walking_distance_travel_mode, "Walking Distance travel mode not found"

    # Call the travel cost service
    result = arcgis.network.analysis.generate_origin_destination_cost_matrix(origins=origins,
                                                                             destinations=destinations,
                                                                             travel_mode=walking_distance_travel_mode
                                                                             )
    print_result(result)

REST API

Unlike Direct request type which allows you to make a request and get back all the results in the response, when working with a Job request type, you need to follow a three step workflow:

  1. Make the submitJob request with the appropriate request parameters to get a job id.
  2. Using the job id, check the job status to see if the job completed successfully.
  3. Use the job id to get one or more results.
cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
5
6
curl https://logistics.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/GPServer/GenerateOriginDestinationCostMatrix/submitJob? \
-d "f=json" \
-d "token=<ACCESS_TOKEN>" \
-d "origins={'features':[{'geometry':{'x':-122.341116,'y':47.61641},'attributes':{'Name':'2200 6th Ave, Seattle, WA, 98121, USA'}}]}" \
-d "destinations={'features':[{'geometry':{'x':-122.339910,'y':47.615270},'attributes':{'Name':'Wells Fargo, 2121 6th Ave, Seattle, WA, 98121, USA','Type':'ATM'}},{'geometry':{'x':-122.341360,'y':47.616220},'attributes':{'Name':'Bank of America, 2200 6th Ave, Seattle, WA, 98121, USA','Type':'ATM'}},{'geometry':{'x':-122.339400,'y':47.613800},'attributes':{'Name':'Sound Community Bank, 2001 5th Ave, Seattle, WA, 98121, USA','Type':'ATM'}},{'geometry':{'x':-122.337977,'y':47.618351},'attributes':{'Name':'Whole Foods Market, 2210 Westlake Ave, Seattle, WA, 98121, USA','Type':'Grocery'}},{'geometry':{'x':-122.337396,'y':47.618669},'attributes':{'Name':'District H, 101 Terry Ave N, Seattle, WA, 98109, USA','Type':'Grocery'}},{'geometry':{'x':-122.344450,'y':47.614170},'attributes':{'Name':'Dans Belltown Grocery, 2221 3rd Ave, Seattle, WA, 98121, USA','Type':'Grocery'}},{'geometry':{'x':-122.340099,'y':47.616020},'attributes':{'Name':'Elm Coffee Roasters Doppler, 2121 7th Ave, Seattle, WA, 98121, USA','Type':'Snacks'}},{'geometry':{'x':-122.340149,'y':47.616090},'attributes':{'Name':'Amazon Go, 2131 7th Ave, Seattle, WA, 98121, USA','Type':'Fast Food'}},{'geometry':{'x':-122.339474,'y':47.615646},'attributes':{'Name':'General Porpoise, 2101 7th Ave, Seattle, WA, 98121, USA','Type':'Snacks'}},{'geometry':{'x':-122.341109,'y':47.618590},'attributes':{'Name':'Denny Park, 800 Denny Way, Seattle, WA, 98109, USA','Type':'Park'}},{'geometry':{'x':-122.337480,'y':47.613740},'attributes':{'Name':'Westlake Square, Westlake Ave, Seattle, WA, 98101, USA','Type':'Park'}},{'geometry':{'x':-122.337530,'y':47.612810},'attributes':{'Name':'McGraw Square, 5th Ave, Seattle, WA, 98101, USA','Type':'Park'}}]}" \
-d "travel_mode={'attributeParameterValues':[{'attributeName':'Avoid Private Roads','parameterName':'Restriction Usage','value':'AVOID_MEDIUM'},{'attributeName':'Walking','parameterName':'Restriction Usage','value':'PROHIBITED'},{'attributeName':'Preferred for Pedestrians','parameterName':'Restriction Usage','value':'PREFER_LOW'},{'attributeName':'WalkTime','parameterName':'Walking Speed (km/h)','value':5},{'attributeName':'Avoid Roads Unsuitable for Pedestrians','parameterName':'Restriction Usage','value':'AVOID_HIGH'}],'description':'Follows paths and roads that allow pedestrian traffic and finds solutions that optimize travel distance.','distanceAttributeName':'Kilometers','id':'yFuMFwIYblqKEefX','impedanceAttributeName':'Kilometers','name':'Walking Distance','restrictionAttributeNames':['Avoid Private Roads','Avoid Roads Unsuitable for Pedestrians','Preferred for Pedestrians','Walking'],'simplificationTolerance':2,'simplificationToleranceUnits':'esriMeters','timeAttributeName':'WalkTime','type':'WALK','useHierarchy':false,'uturnAtJunctions':'esriNFSBAllowBacktrack'}"
Response (JSON)
Use dark colors for code blocksCopy
1
2
3
4
{
  "jobId": "je24b0da397c34b56956fda7107094872",
  "jobStatus": "esriJobSubmitted"
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.