Travel cost matrix

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.

The travel cost matrix service allows you to create an OD cost matrix using various modes of travel from every origin to every destination. You can optionally:

Specify the maximum number of destinations to find for each origin instead of all.
Provide the maximum time or distance to travel when searching for destinations. Once this cutoff is reached, the service will not search for any more destinations from an origin.
Apply current traffic conditions when calculating the cost of travel between origins and destinations.

How a travel cost matrix works

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

Starting locations from which to travel to the destinations.
Ending locations to travel to from the origins.
The type of travel for the analysis.
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.

Request limits

Limit	Direct	Job
Maximum number of origins:	10	1,000
Maximum number of destinations:	10	1,000
Maximum transaction time:	5 minutes	60 minutes
Maximum number of point barriers:	250	250
Maximum number of street features intersected by polyline barriers:	500	500
Maximum number of street features intersected by polygon barriers:	2,000	2,000
Maximum straight-line distance for the walking travel mode: (If the straight-line distance between any incidents or facilities is greater than this limit, the analysis will fail when the walking restriction is used.)	27 miles (43.45 kilometers)	27 miles (43.45 kilometers)
Force hierarchy beyond a straight-line distance of: (If the straight-line distance between any origin or destination is greater than the limit shown here, the analysis uses hierarchy, even if the travel mode defines not to use hierarchy.)	50 miles (80.46 kilometers)	50 miles (80.46 kilometers)
Maximum snap tolerance: (If the distance between an input point and its nearest traversable street is greater than the distance specified here, the point is excluded from the analysis.)	12.42 miles (20 kilometers)	12.42 miles (20 kilometers)

Required parameters

Name	Description	Examples
`f`	The format of the data returned.	`f=json` `f=pjson`
`token`	An 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 blocks

Copy

1
https://route-api.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/NAServer/OriginDestinationCostMatrix_World/solveODCostMatrix?<parameters>

Run in Postman

Use dark colors for code blocks

Copy

1
https://route.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/NAServer/OriginDestinationCostMatrix_World/solveODCostMatrix?<parameters>

Run in Postman

Key parameters

Name (Direct)	Description	Examples
`origins`	Starting locations from which to travel to the destinations.	`origins=-118.245843,34.057794;-117.16274,32.719178`
`destinations`	Ending locations to travel to from the origins.	`destinations=-117.182676,34.055909;-118.144184,34.147832`
`travelMode`	The mode of transportation such as driving a car or a truck or walking.	`travelMode=`JSON Object
`defaultTargetDestinationCount`	The 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`
`defaultCutoff`	The 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 blocks

Copy

1
https://logistics.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/GPServer/GenerateOriginDestinationCostMatrix/submitJob?<parameters>

Run in Postman

Key parameters

Name (Direct)	Description	Examples
`origins`	Starting locations from which to travel to the destinations.	`origins={"features":[{"geometry":{"x":-118.245843,"y":34.057794}},{"geometry":{"x":-117.16274,"y":32.719178}}]}`
`destinations`	Ending locations to travel to from the origins.	`destinations={"features":[{"geometry":{"x":-117.182676,"y":34.055909}},{"geometry":{"x":-118.144184,"y":34.147832}}]}`
`travel_mode`	The mode of transportation such as driving a car or a truck or walking.	`travel_mode=`JSON Object
`number_of_destinations_to_find`	The 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`
`cutoff`	The 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 blocks

Copy

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)

Expand

Go to API reference

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

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}}]}"

Run in Postman

Use dark colors for code blocksCopy
{
  "messages": [],
  "odCostMatrix": {
    "costAttributeNames": [
      "TravelTime",
      "Miles",
      "Kilometers"
    ],
    "101": {
      "101": [
        0,
        0,
        0
      ],
      "102": [
        1092.7348608174257,
        1046.4209599692097,
        1684.0512934006936
      ],
      "103": [
Expand

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.

The example uses some amenities in Seattle, USA. In case you need to adapt this example to your area of interest, you can use the ArcGIS Geocoding service for finding different amenities by category name. For example, the below request allows you to find three ATMs near a location in Seattle.

Use dark colors for code blocksCopy
curl https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates? \
-d "f=json" \
-d "token=<ACCESS_TOKEN>" \
-d "category=ATM" \
-d "outFields=LongLabel,Type" \
-d "maxLocations=3" \
-d "location=-122.340013,47.616004"

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 blocks

Copy

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)

Expand

Go to API reference

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:

Make the submitJob request with the appropriate request parameters to get a job id.
Using the job id, check the job status to see if the job completed successfully.
Use the job id to get one or more results.

cURL

HTTP

Use dark colors for code blocks

Copy

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'}"

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "jobId": "je24b0da397c34b56956fda7107094872",
  "jobStatus": "esriJobSubmitted"
}

Request

cURL

HTTP

Use dark colors for code blocks

Copy

1
2
3
curl https://logistics.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/GPServer/GenerateOriginDestinationCostMatrix/jobs/je24b0da397c34b56956fda7107094872? \
-d "f=json" \
-d "token=<ACCESS_TOKEN>"

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "jobId": "je24b0da397c34b56956fda7107094872",
  "jobStatus": "esriJobSucceeded",
  "results": {
    "Solve_Succeeded": {
      "paramUrl": "results/Solve_Succeeded"
    },
    "Output_Origin_Destination_Lines": {
      "paramUrl": "results/Output_Origin_Destination_Lines"
    },
    "Output_Origins": {
      "paramUrl": "results/Output_Origins"
    },
    "Output_Destinations": {
      "paramUrl": "results/Output_Destinations"
    },
    "Output_Network_Analysis_Layer": {
      "paramUrl": "results/Output_Network_Analysis_Layer"
    },
    "Output_Result_File": {
Expand

Request

cURL

HTTP

Use dark colors for code blocks

Copy

1
2
3
curl https://logistics.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/GPServer/GenerateOriginDestinationCostMatrix/jobs/je24b0da397c34b56956fda7107094872/results/Output_Origin_Destination_Lines? \
-d "f=json" \
-d "token=<ACCESS_TOKEN>"

Run in Postman

Response (JSON)

Use dark colors for code blocks

Copy

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
{
  "paramName": "Output_Origin_Destination_Lines",
  "dataType": "GPFeatureRecordSetLayer",
  "value": {
    "geometryType": "esriGeometryPolyline",
    "spatialReference": {
      "wkid": 4326,
      "latestWkid": 4326
    },
    "fields": [
      // one or more field definitions
    ],
    "features": [
      {
        "attributes": {
          "DestinationRank": 1,
          "Total_Time": 0.11971298133015928,
          "Total_Distance": 0.0099760817775132737,
          "OriginName": "2200 6th Ave, Seattle, WA, 98121, USA",
          "DestinationName": "Bank of America, 2200 6th Ave, Seattle, WA, 98121, USA"
          // more field values
        }
      },
      {
        "attributes": {
          "DestinationRank": 2,
          "Total_Time": 1.1702233937864959,
          "Total_Distance": 0.097518616148874637,
          "OriginName": "2200 6th Ave, Seattle, WA, 98121, USA",
          "DestinationName": "Elm Coffee Roasters Doppler, 2121 7th Ave, Seattle, WA, 98121, USA"
          // more field values
        }
      }
      // Additional origin-destination distances
    ],
    "exceededTransferLimit": false
  }
}

See full response