Utilities service GetTravelModes tool

The Utilities service contains tools that provide auxiliary information for working with network analysis services available with ArcGIS Online. Currently, the Utilities service contains two tools, GetTravelModes and GetToolInfo. The GetTravelModes tool returns a list of travel modes configured for your organization that can be used with network analysis services. A travel mode represents a means of transportation, such as driving or walking. Travel modes are essentially templates consisting of a long list of travel settings.

The GetTravelModes tool is meant to be used by different apps to display the name and optionally the description of the available travel modes in their user experience. An Administrator of your organization can configure travel modes to change the properties of the default travel modes provided by ArcGIS Online, add new travel modes that better reflect your organization’s workflows, or remove travel modes that are not suitable for your organization’s workflows.

CautionCaution:

When called using a token obtained through app logins, the tool always returns the default travel modes even if your organization has customized the travel modes. In order to get the travel modes from your organization, you should call this tool using a token that is obtained using a named user login. To run this tool in scenarios where you do not want the end users of your app to provide any credentials, you can use the following workflows:

  • Add the Utilities service (which contains the GetTravelModes tool) as an ArcGIS Server web service item using its REST URL (https://logistics.arcgis.com/arcgis/rest/services/World/Utilities/GPServer) and storing your named user credentials with the service item. You can then call the GetTravelModes tool using the new URL provided by the service item. For example, after you have added the web service item, the new URL to call GetTravelModes tool will be of the following form https://utility.arcgis.com/usrsvcs/servers/<itemId>/rest/services/World/Utilities/GPServer/GetTravelModes/execute?parameters.
  • Use a self-hosted proxy service. For the proxy configuration, set the Utilities service REST URL as the value for the url property, and the named user credentials for the username and password properties.

Request URL

You can make a request to the GetTravelModes tool from the Utilities service using the URL of the following form:

https://logistics.arcgis.com/arcgis/rest/services/World/Utilities/GPServer/GetTravelModes/execute?parameters

Request parameters

The GetTravelModes request takes the token and f parameters, which are both required.

Required parameters

token

Use this parameter to specify a token that provides the identity of a user that has the permissions to access the service. Accessing services provided by Esri provides more information on how such an access token can be obtained.

f

Use this parameter to specify the response format. Choose either json or pjson, for example, f=json. The pjson value is used for printing the JSON response in a pretty format.

JSON response

The request to GetTravelModes returns a JSON response that contains any warning messages from the service execution as well as an array of results. Each result in this array contains the value for the output parameters, supportedTravelModes and defaultTravelMode. If the request fails to execute, the response only contains the error property that contains the error messages.

JSON response syntax for successful request
{
    "results": [
        {
            "paramName": "<paramName1>",
            "dataType": "<dataType1>",
            "value": <valueLiteralOrObject1>
        },
        {
            "paramName": "<paramName2>",
            "dataType": "<dataType2>",
            "value": <valueLiteralOrObject2>
        }
    ],
    "messages": [
        {
            "type": "<type1>",
            "description": "<description1>"
        },
        {
            "type": "<type2>",
            "description": "<description2>"
        }
    ]
}
JSON response syntax for failed request.
{
    "error": {
        "code": <code>,
        "message": "<message>",
        "details": [
            "<details>"
        ]
    }
}

Output parameters

Upon successful execution, the service returns a list of supported travel modes and the default travel mode as the following output parameters:

supportedTravelModes

Use this parameter to a get a list of travel modes supported by your organization.

The following provides a description of fields that are returned for each travel mode:

  • ObjectID—A unique identifier for the travel mode. This identifier is automatically generated by the service.
  • Name—The name of the travel mode. This field can include the localized travel mode name and cannot be used to uniquely identify a travel mode based on its name. Use the AltName field for this instead.
  • TravelModeId—A unique identifier for the travel mode. This identifier is created every time a new travel mode is added but remains the same for existing travel modes.
  • TravelMode—The travel mode setting for a given travel mode. The value is a string representing a JSON object. When calling the network analysis services, you need to convert this string into a JSON object using your API.
  • AltName—The name of the travel mode that does not change based on the profile language of the signed in user. This value can be used to uniquely identify a travel mode based on its name, unlike the Name field.

The supportedTravelModes parameter is returned as a JSON feature set with the following syntax:

{
    "paramName": "supportedTravelModes",
    "dataType": "GPRecordSet",
    "value": {
        "displayFieldName": "",
        "fields": [
            {
                "name": "<field1Name>",
                "type": "<field1Type>",
                "alias": "<field1Alias>",
                "length": "<field1Length>" //length is included only for esriFieldTypeString
            },
            {
                "name": "<field2Name>",
                "type": "<field2Type>",
                "alias": "<field2Alias>",
                "length": "<field2Length>"
            }
        ],
        "features": [
            {
                "attributes": {
                    "<field1>": <value11>,
                    "<field2>": <value12>
                }
            },
            {
                "attributes": {
                    "<field1>": <value21>,
                    "<field2>": <value22>
                }
            }
        ],
        "exceededTransferLimit": <true|false>
    }
}

The following shows an example of the supportedTravelModes parameter.

NoteNote:

Because the response is quite verbose, the repeated elements within the response are abbreviated for clarity.

{
    "paramName": "supportedTravelModes",
    "dataType": "GPRecordSet",
    "value": {
        "displayFieldName": "",
        "fields": [
            {
                "name": "ObjectID",
                "type": "esriFieldTypeOID",
                "alias": "ObjectID"
            },
            {
                "name": "Name",
                "type": "esriFieldTypeString",
                "alias": "Travel Mode Name",
                "length": 255
            },
            {
                "name": "TravelModeId",
                "type": "esriFieldTypeString",
                "alias": "Travel Mode Identifier",
                "length": 50
            },
            {
                "name": "TravelMode",
                "type": "esriFieldTypeString",
                "alias": "Travel Mode Settings",
                "length": 65536
            },
            {
                "name": "AltName",
                "type": "esriFieldTypeString",
                "alias": "Alternate Travel Mode Name",
                "length": 255
            }
        ],
        "features": [
            {
                "attributes": {
                    "ObjectID": 1,
                    "Name": "Walking Time",
                    "TravelModeId": "caFAgoThrvUpkFBW",
                    "TravelMode": "{\"restrictionAttributeNames\": [\"Preferred for Pedestrians\", \"Walking\"], \"description\": \"Follows paths and roads that allow pedestrian traffic and finds solutions that optimize travel time. The walking speed is set to 5 kilometers per hour.\", \"impedanceAttributeName\": \"WalkTime\", \"simplificationToleranceUnits\": \"esriMeters\", \"uturnAtJunctions\": \"esriNFSBAllowBacktrack\", \"useHierarchy\": false, \"simplificationTolerance\": 2, \"timeAttributeName\": \"WalkTime\", \"distanceAttributeName\": \"Miles\", \"type\": \"WALK\", \"id\": \"caFAgoThrvUpkFBW\", \"attributeParameterValues\": [{\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Walking\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Preferred for Pedestrians\", \"value\": \"PREFER_LOW\"}, {\"parameterName\": \"Walking Speed (km/h)\", \"attributeName\": \"WalkTime\", \"value\": 5}], \"name\": \"Walking Time\"}",
                    "AltName": "Walking Time"
                }
            },
            {
                "attributes": {
                    "ObjectID": 2,
                    "Name": "Rural Driving Distance",
                    "TravelModeId": "Yzk3NjI1NTU5NjVj",
                    "TravelMode": "{\"restrictionAttributeNames\": [\"Avoid Carpool Roads\", \"Avoid Express Lanes\", \"Avoid Gates\", \"Avoid Private Roads\", \"Driving an Automobile\", \"Roads Under Construction Prohibited\", \"Through Traffic Prohibited\"], \"description\": \"Models the movement of cars and other similar small automobiles, such as pickup trucks, and finds solutions that optimize travel distance. Travel obeys one-way roads, avoids illegal turns, and follows other rules that are specific to cars, but does not discourage travel on unpaved roads.\", \"impedanceAttributeName\": \"Miles\", \"simplificationToleranceUnits\": \"esriMeters\", \"uturnAtJunctions\": \"esriNFSBAtDeadEndsAndIntersections\", \"useHierarchy\": true, \"simplificationTolerance\": 10, \"timeAttributeName\": \"TravelTime\", \"distanceAttributeName\": \"Miles\", \"type\": \"AUTOMOBILE\", \"id\": \"Yzk3NjI1NTU5NjVj\", \"attributeParameterValues\": [{\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Private Roads\", \"value\": \"AVOID_MEDIUM\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Driving an Automobile\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Through Traffic Prohibited\", \"value\": \"AVOID_HIGH\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Roads Under Construction Prohibited\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Gates\", \"value\": \"AVOID_MEDIUM\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Express Lanes\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Carpool Roads\", \"value\": \"PROHIBITED\"}], \"name\": \"Rural Driving Distance\"}",
                    "AltName": "Rural Driving Distance"
                }
            },
            //.... additional travel modes
            
        ],
        "exceededTransferLimit": false
    }
}

defaultTravelMode

Use this parameter to get the default travel mode to be used by the user interface of your application. The value property returns the travel mode ID that corresponds to the TravelModeId property of the attributes objects returned by the supportedTravelModes output parameter.

The defaultTravelMode parameter is returned as a JSON feature set with the following syntax:

{
    "paramName": "defaultTravelMode",
    "dataType": "GPString",
    "value": "<travelModeId>"
    }
}

The following shows an example of the defaultTravelMode parameter:

{
    "paramName": "defaultTravelMode",
    "dataType": "GPString",
    "value": "FEgifRtFndKNcJMJ"
}

Examples

NoteNote:

If you copy and paste the request URL from the examples into a web browser, you will get an invalid token error message. You need to replace <yourToken> with a valid token. See Accessing services provided by Esri to see how to generate one.

Get a list of supported travel modes when the user profile language is English

In this example, you will get a list of all the travel modes that are supported in your ArcGIS Online organization. The language of the signed in user is English. The Name and AltName fields for travel modes have identical values.

Request URL to execute the GetTravelModes tool

http://logistics.arcgis.com/arcgis/rest/services/World/Utilities/GPServer/GetTravelModes/execute?token=<yourToken>&f=pjson

JSON response

{
    "results": [
        {
            "paramName": "supportedTravelModes",
            "dataType": "GPRecordSet",
            "value": {
                "displayFieldName": "",
                "fields": [
                    {
                        "name": "ObjectID",
                        "type": "esriFieldTypeOID",
                        "alias": "ObjectID"
                    },
                    {
                        "name": "Name",
                        "type": "esriFieldTypeString",
                        "alias": "Travel Mode Name",
                        "length": 255
                    },
                    {
                        "name": "TravelModeId",
                        "type": "esriFieldTypeString",
                        "alias": "Travel Mode Identifier",
                        "length": 50
                    },
                    {
                        "name": "TravelMode",
                        "type": "esriFieldTypeString",
                        "alias": "Travel Mode Settings",
                        "length": 65536
                    },
                    {
                        "name": "AltName",
                        "type": "esriFieldTypeString",
                        "alias": "Alternate Travel Mode Name",
                        "length": 255
                    }
                ],
                "features": [
                    {
                        "attributes": {
                            "ObjectID": 1,
                            "Name": "Walking Time",
                            "TravelModeId": "caFAgoThrvUpkFBW",
                            "TravelMode": "{\"restrictionAttributeNames\": [\"Preferred for Pedestrians\", \"Walking\"], \"description\": \"Follows paths and roads that allow pedestrian traffic and finds solutions that optimize travel time. The walking speed is set to 5 kilometers per hour.\", \"impedanceAttributeName\": \"WalkTime\", \"simplificationToleranceUnits\": \"esriMeters\", \"uturnAtJunctions\": \"esriNFSBAllowBacktrack\", \"useHierarchy\": false, \"simplificationTolerance\": 2, \"timeAttributeName\": \"WalkTime\", \"distanceAttributeName\": \"Miles\", \"type\": \"WALK\", \"id\": \"caFAgoThrvUpkFBW\", \"attributeParameterValues\": [{\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Walking\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Preferred for Pedestrians\", \"value\": \"PREFER_LOW\"}, {\"parameterName\": \"Walking Speed (km/h)\", \"attributeName\": \"WalkTime\", \"value\": 5}], \"name\": \"Walking Time\"}",
                            "AltName": "Walking Time"
                        }
                    },
                    {
                        "attributes": {
                            "ObjectID": 2,
                            "Name": "Rural Driving Distance",
                            "TravelModeId": "Yzk3NjI1NTU5NjVj",
                            "TravelMode": "{\"restrictionAttributeNames\": [\"Avoid Carpool Roads\", \"Avoid Express Lanes\", \"Avoid Gates\", \"Avoid Private Roads\", \"Driving an Automobile\", \"Roads Under Construction Prohibited\", \"Through Traffic Prohibited\"], \"description\": \"Models the movement of cars and other similar small automobiles, such as pickup trucks, and finds solutions that optimize travel distance. Travel obeys one-way roads, avoids illegal turns, and follows other rules that are specific to cars, but does not discourage travel on unpaved roads.\", \"impedanceAttributeName\": \"Miles\", \"simplificationToleranceUnits\": \"esriMeters\", \"uturnAtJunctions\": \"esriNFSBAtDeadEndsAndIntersections\", \"useHierarchy\": true, \"simplificationTolerance\": 10, \"timeAttributeName\": \"TravelTime\", \"distanceAttributeName\": \"Miles\", \"type\": \"AUTOMOBILE\", \"id\": \"Yzk3NjI1NTU5NjVj\", \"attributeParameterValues\": [{\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Private Roads\", \"value\": \"AVOID_MEDIUM\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Driving an Automobile\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Through Traffic Prohibited\", \"value\": \"AVOID_HIGH\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Roads Under Construction Prohibited\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Gates\", \"value\": \"AVOID_MEDIUM\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Express Lanes\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Carpool Roads\", \"value\": \"PROHIBITED\"}], \"name\": \"Rural Driving Distance\"}",
                            "AltName": "Rural Driving Distance"
                        }
                    },
                    //additional travel modes
                ],
                "exceededTransferLimit": false
            }
        },
        {
            "paramName": "defaultTravelMode",
            "dataType": "GPString",
            "value": "FEgifRtFndKNcJMJ"
        }
    ],
    "messages": []
}

Get a list of supported travel modes when the user profile language is Spanish

In this example, you will get a list of all the travel modes that are supported in your ArcGIS Online organization. The language of the signed in user is Spanish. The Name field provides the travel mode name in Spanish and the AltName field provides the travel mode name in English. Regardless of the user profile language, the AltName field always provides the travel mode name in English.

Request URL to execute the GetTravelModes tool

http://logistics.arcgis.com/arcgis/rest/services/World/Utilities/GPServer/GetTravelModes/execute?token=<yourToken>&f=pjson

JSON response

{
    "results": [
        {
            "paramName": "supportedTravelModes",
            "dataType": "GPRecordSet",
            "value": {
                "displayFieldName": "",
                "fields": [
                    {
                        "name": "ObjectID",
                        "type": "esriFieldTypeOID",
                        "alias": "ObjectID"
                    },
                    {
                        "name": "Name",
                        "type": "esriFieldTypeString",
                        "alias": "Travel Mode Name",
                        "length": 255
                    },
                    {
                        "name": "TravelModeId",
                        "type": "esriFieldTypeString",
                        "alias": "Travel Mode Identifier",
                        "length": 50
                    },
                    {
                        "name": "TravelMode",
                        "type": "esriFieldTypeString",
                        "alias": "Travel Mode Settings",
                        "length": 65536
                    },
                    {
                        "name": "AltName",
                        "type": "esriFieldTypeString",
                        "alias": "Alternate Travel Mode Name",
                        "length": 255
                    }
                ],
                "features": [
                    {
                        "attributes": {
                            "ObjectID": 1,
                            "Name": "Tiempo a pie",
                            "TravelModeId": "caFAgoThrvUpkFBW",
                            "TravelMode": "{\"attributeParameterValues\": [{\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Private Roads\", \"value\": \"AVOID_MEDIUM\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Walking\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Preferred for Pedestrians\", \"value\": \"PREFER_LOW\"}, {\"parameterName\": \"Walking Speed (km/h)\", \"attributeName\": \"WalkTime\", \"value\": 5}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Roads Unsuitable for Pedestrians\", \"value\": \"AVOID_HIGH\"}], \"description\": \"Sigue caminos y carreteras que permiten el paso de peatones y encuentra alternativas para optimizar el tiempo de viaje. La velocidad media al caminar se establece en 5 kil\\u00f3metros por hora.\", \"impedanceAttributeName\": \"WalkTime\", \"simplificationToleranceUnits\": \"esriMeters\", \"uturnAtJunctions\": \"esriNFSBAllowBacktrack\", \"restrictionAttributeNames\": [\"Avoid Private Roads\", \"Avoid Roads Unsuitable for Pedestrians\", \"Preferred for Pedestrians\", \"Walking\"], \"useHierarchy\": false, \"simplificationTolerance\": 2, \"timeAttributeName\": \"WalkTime\", \"distanceAttributeName\": \"Kilometers\", \"type\": \"WALK\", \"id\": \"caFAgoThrvUpkFBW\", \"name\": \"Tiempo a pie\"}",
                            "AltName": "Walking Time"
                        }
                    },
                    {
                        "attributes": {
                            "ObjectID": 2,
                            "Name": "Distancia de conducción (medio rural)",
                            "TravelModeId": "Yzk3NjI1NTU5NjVj",
                            "TravelMode": "{\"attributeParameterValues\": [{\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Private Roads\", \"value\": \"AVOID_MEDIUM\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Driving an Automobile\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Through Traffic Prohibited\", \"value\": \"AVOID_HIGH\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Roads Under Construction Prohibited\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Gates\", \"value\": \"AVOID_MEDIUM\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Express Lanes\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Avoid Carpool Roads\", \"value\": \"PROHIBITED\"}], \"description\": \"Configura el tr\\u00e1nsito de coches y otros autom\\u00f3viles peque\\u00f1os, como furgonetas, y encuentra alternativas para optimizar la distancia de viaje. Respeta calles de un sentido, evita giros prohibidos y sigue otras normas espec\\u00edficas para coches, sin descartar carreteras sin pavimentar.\", \"impedanceAttributeName\": \"Kilometers\", \"simplificationToleranceUnits\": \"esriMeters\", \"uturnAtJunctions\": \"esriNFSBAtDeadEndsAndIntersections\", \"restrictionAttributeNames\": [\"Avoid Carpool Roads\", \"Avoid Express Lanes\", \"Avoid Gates\", \"Avoid Private Roads\", \"Driving an Automobile\", \"Roads Under Construction Prohibited\", \"Through Traffic Prohibited\"], \"useHierarchy\": true, \"simplificationTolerance\": 10, \"timeAttributeName\": \"TravelTime\", \"distanceAttributeName\": \"Kilometers\", \"type\": \"AUTOMOBILE\", \"id\": \"Yzk3NjI1NTU5NjVj\", \"name\": \"Distancia de conducci\\u00f3n (medio rural)\"}",
                           "AltName": "Rural Driving Distance"
                        }
                    },
                    //additional travel modes
                ],
                "exceededTransferLimit": false
            }
        },
        {
            "paramName": "defaultTravelMode",
            "dataType": "GPString",
            "value": "FEgifRtFndKNcJMJ"
        }
    ],
    "messages": []
}
7/5/2017