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.

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
`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 blocksCopy
``https://route-api.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/NAServer/OriginDestinationCostMatrix_World/solveODCostMatrix?<parameters>``
Use dark colors for code blocksCopy
``https://route.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/NAServer/OriginDestinationCostMatrix_World/solveODCostMatrix?<parameters>``

Key parameters

Name (Direct)DescriptionExamples
`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 blocksCopy
``https://logistics.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/GPServer/GenerateOriginDestinationCostMatrix/submitJob?<parameters>``

Key parameters

Name (Direct)DescriptionExamples
`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 blocksCopy
``````    # 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
``````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
``````    # 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
``````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
``````{
"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.