Connect Origins to Destinations

originsLayer

(Required)

The starting point or points of the routes to be generated.

Syntax: As described in detail in the Feature Input topic, this parameter can be

• a URL to a feature service layer with an optional filter to select specific features, or
• a feature collection.

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

destinationsLayer

(Required)

Syntax: As described in detail in the Feature Input topic, this parameter can be

• a URL to a feature service layer with an optional filter to select specific features, or
• a feature collection.

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

measurementType

(Required)

The origins and destinations can be connected by measuring straight-line distance, or by measuring travel time or travel distance along a street network using various modes of transportation known as travel modes.

Valid values are a string,StraightLine, which indicates Euclidean distance to be used as distance measure or a JSON object representing settings for a travel mode.

Travel modes are managed in ArcGIS Online and can be configured by the administrator of your organization to better reflect your organization's workflows. You need to specify the JSON object containing the settings for a travel mode supported by your organization. To get a list of supported travel modes, execute the GetTravelModes tool from the Utilities service.

When using a travel mode for the measurementType, the value should be a JSON object representing travel mode settings. When you use the GetTravelModes tool from the Utilities service, You get a string representing the travel mode JSON. You need to convert this string to a valid JSON object using your API and then pass the JSON object as the value for the measurementType parameter.

For example, below is a string representing the Walking Time travel mode as returned by the GetTravelModes tool.

"{\"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}], \"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\", \"restrictionAttributeNames\": [\"Preferred for Pedestrians\", \"Walking\"], \"useHierarchy\": false, \"simplificationTolerance\": 2, \"timeAttributeName\": \"WalkTime\", \"distanceAttributeName\": \"Miles\", \"type\": \"WALK\", \"id\": \"caFAgoThrvUpkFBW\", \"name\": \"Walking Time\"}"

The above value should be converted to a valid JSON object and passed as the value for the measurementType parameter

{
  "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
    }
  ],
  "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",
  "restrictionAttributeNames": [
    "Preferred for Pedestrians",
    "Walking"
  ],
  "useHierarchy": false,
  "simplificationTolerance": 2,
  "timeAttributeName": "WalkTime",
  "distanceAttributeName": "Miles",
  "type": "WALK",
  "id": "caFAgoThrvUpkFBW",
  "name": "Walking Time"
}

originsLayerRouteIDField

Specify the field in the origins layer containing the IDs that pair origins with destinations.

• The ID values must uniquely identify points in the origins layer.

• Each ID value must also correspond with exactly one route ID value in the destinations layer. Route IDs that match across the layers create origin-destination pairs, which the tool connects together.

• Specifying originsLayerRouteIDField is optional when there is exactly one point feature in the origins or destinations layer. The tool will connect all origins to the one destination or the one origin to all destinations, depending on which layer contains one point.

destinationsLayerRouteIDField

Specify the field in the destinations layer containing the IDs that pair origins with destinations.

• The ID values must uniquely identify points in the destinations layer.

• Each ID value must also correspond with exactly one route ID value in the origins layer. Route IDs that match across the layers create origin-destination pairs, which the tool connects together.

• Specifying destinationsLayerRouteIDField is optional when there is exactly one point feature in the origins or destinations layer. The tool will connect all origins to the one destination or the one origin to all destinations, depending on which layer contains one point.

timeOfDay

Specify whether travel times should consider traffic conditions. To use traffic in the analysis, set measurementType to a travel mode object whose impedanceAttributeName property is set to TravelTime and assign a value to timeOfDay. (A travel mode with other impedanceAttributeName values don't support traffic.) The timeOfDay value represents the time at which travel begins, or departs, from the origin points. The time is specified as Unix time (milliseconds since midnight, January 1 1970).

The service supports two kinds of traffic: typical and live. Typical traffic references travel speeds that are made up of historical averages for each five-minute interval spanning a week. Live traffic retrieves speeds from a traffic feed that processes phone probe records, sensors, and other data sources to record actual travel speeds and predict speeds for the near future.

The data coverage page shows the countries Esri currently provides traffic data for.

Typical Traffic:

To ensure the task uses typical traffic in locations where it is available, choose a time and day of the week, and then convert the day of the week to one of the following dates from 1990:

• Monday—1/1/1990
• Tuesday—1/2/1990
• Wednesday—1/3/1990
• Thursday—1/4/1990
• Friday—1/5/1990
• Saturday—1/6/1990
• Sunday—1/7/1990

Set the time and date as Unix time in milliseconds.

For example, to solve for 1:03 p.m. on Thursdays, set the time and date to 1:03 p.m., 4 January 1990; and convert to milliseconds (631458180000).

Note:

Although the dates representing days of the week are from 1990, typical traffic is calculated from recent traffic trends—usually over the last several months.

Live Traffic:

To use live traffic when and where it is available, choose a time and date and convert to Unix time.

Esri saves live traffic data for 12 hours and references predictive data extending 12 hours into the future. If the time and date you specify for this parameter is outside the 24-hour time window, or the travel time in the analysis continues past the predictive data window, the task falls back to typical traffic speeds.

Note:

• This parameter is ignored when measurementType is set to a travel mode whose impedanceAttributeName property value is not set to TravelTime.
• The time zone for timeOfDay can be UTC or the time zone or zones in which the points in originsLayer are located. Specify time zones with the timeZoneForTimeOfDay parameter.

Syntax: The number of milliseconds since the Unix epoch (January 1, 1970).

Examples:

• "timeOfDay": 631458180000 // 13:03, 4 January 1990. Typical traffic on Thursdays at 1:03 p.m.
• "timeOfDay": 631731600000 // 17:00, 7 January 1990. Typical traffic on Sundays at 5:00 p.m.
• "timeOfDay": 1413964800000 // 8:00, 22 October 2014. If the current time is between 8:00 p.m., 21 Oct. 2014 and 8:00 p.m., 22 Oct. 2014, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.
• "timeOfDay": 1426674000000 // 10:20, 18 March 2015. If the current time is between 10:20 p.m., 17 Mar. 2015 and 10:20 p.m., 18 Mar. 2015, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.

timeZoneForTimeOfDay

Specify the time zone or zones of the timeOfDay parameter. There are two options: GeoLocal (default) and UTC.

GeoLocal:

The timeOfDay value refers to the time zone in which the originsLayer points are located.

GeoLocal Illustration: Setting timeOfDay to 9:00 a.m., 4 January 1990 (631443600000 milliseconds); timeZoneForTimeOfDay to GeoLocal; and submitting a valid request causes the drive times for origins in the Eastern Time Zone to start at 9:00 a.m. (2:00 p.m. UTC).

UTC:

The timeOfDay value refers to Coordinated Universal Time (UTC).

UTC Illustration: Setting timeOfDay to 9:00 a.m., 4 January 1990 (631443600000 milliseconds) and timeZoneForTimeOfDay to UTC, the start time for origins in the Eastern Time Zone is 4:00 a.m. Eastern Time (9:00 a.m. UTC).

Values: GeoLocal | UTC

outputName

If provided, the task will create a feature service of the results. You define the name of the service. If outputName is not supplied, the task will return a feature collection.

{
  "serviceProperties": {
    "name": "<service name>"
  }
}

context

Context contains additional settings that affect task execution. For Connect Origins to Destinations, there are two settings.

1. Extent (extent)—a bounding box that defines the analysis area. Only those features in the originsLayer and destinationsLayer that intersect the bounding box will be analyzed.

2. Output Spatial Reference (outSR)

   • If the output is a feature service, the spatial reference will be the same as originsLayer. Setting outSR for feature services has no effect.
   • If the output is a feature collection, the features will be in the spatial reference of the outSR value or the spatial reference of originsLayer when outSR is not specified.

{
"extent" : {extent}
"outSR" : {spatial reference}
}

f

The response format. The default response format is html.

Values: html | json

routesLayer

The output layer containing the routes that connect origins to destinations.

{"url": 
"http://<analysis url>/ConnectOriginsToDestinations/jobs/<jobId>/results/routesLayer"

The result has properties for parameter name, data type, and value. The contents of value depends on the outputName parameter provided in the initial request.

• If outputName was provided, value contains the url to the feature service layer.
  {
  "paramName":"routesLayer", 
  "dataType":"GPString",
  "value":{"url":"<hosted feature service layer url>"}
  }
  

• If outputName was not provided, value contains a feature collection.
  {
  "paramName": "routesLayer",
  "dataType": "GPString",
  "value":{"layerDefinition": {}, "featureSet": {}}
  }
  

See Feature Output for more information about how the result layer or collection is accessed.

Fields in the output:

The result layer has the following attributes:

• RouteName—Unique ID values of the origin and destination that are connected by the route line.
• Total_Minutes—This field is present only when measurementType is set to a travel mode. This is the cumulative travel time, in minutes, from the origin to the destination.
• Total_Miles—This is the cumulative travel distance, in miles, from the origin to the destination.
• Total_Kilometers—This is the cumulative travel distance, in kilometers, from the origin to the destination.
• StartTime—This field is present only when a timeOfDay value is provided in the input. It specifies the time and date the route departs from the origin. The time is presented using the time zone in which the origin is located.
• EndTime—This field is present only when a timeOfDay value is provided in the input. It specifies the time and date the route arrives at the destination. The time is presented using the time zone in which the destination is located.
• OriginOID—This field contains unique identifiers of the points in the origins layer.
• DestinationOID—This field contains unique identifiers of the points in the destinations layer.

unassignedOriginsLayer

The input origins that couldn't be included in the solution.

{"url": 
"http://<analysis url>/ConnectOriginsToDestinations/jobs/<jobId>/results/UnassignedOriginsLayer"}

The result has properties for parameter name, data type, and value. The contents of value depends on the outputName parameter provided in the initial request.

• If outputName was provided, value contains the url to the feature service layer.
  {
  "paramName":"unassignedOriginsLayer", 
  "dataType":"GPString",
  "value":{"url":"<hosted featureservice layer url>"}
  }
  

• If outputName was not provided, value contains a feature collection.
  {
  "paramName": "unassignedOriginsLayer",
  "dataType": "GPString",
  "value":{"layerDefinition": {}, "featureSet": {}}
  }
  

Fields in the output:

• Status—Indicates why the origin was not connected to a destination.

unassignedDestinationsLayer

The input destinations that couldn't be included in the solution.

{"url": 
"http://<analysis url>/ConnectOriginsToDestinations/jobs/<jobId>/results/UnassignedDestinationsLayer"}

The result has properties for parameter name, data type, and value. The contents of value depends on the outputName parameter provided in the initial request.

• If outputName was provided, value contains the url to the feature service layer.
  {
  "paramName":"unassignedDestinationsLayer", 
  "dataType":"GPString",
  "value":{"url":"<hosted featureservice layer url>"}
  }
  

• If outputName was not provided, value contains a feature collection.
  {
  "paramName": "unassignedDestinationsLayer",
  "dataType": "GPString",
  "value":{"layerDefinition": {}, "featureSet": {}}
  }
  

Fields in the output:

• Status—Indicates why the destination was not connected to an origin.