The Connect Origins to Destinations task measures the travel time or distance between pairs of points.
Using this tool, you can:
- Calculate the total distance or time commuters travel on their home-to-work trips.
- Measure how far customers are traveling to shop at your stores. Use this information to define your market reach, especially when targeting advertising campaigns or choosing new store locations.
- Calculate the expected trip mileage for your fleet of vehicles. Afterward, run the Summarize Within tool to report mileage by state or other region.
You provide starting and ending points, and the tool returns a layer containing route lines, including measurements, between the paired origins and destinations.
Request URL
http://<analysis url>/connectOriginsToDestinations/submitJob
Limits
There are limits to the number of features that can be processed.
- originsLayer—maximum 5,000 features
- destinationsLayer—maximum 5,000 features
- pointBarrierLayer—Maximum 250 features.
- lineBarrierLayer—An error will occur if the number of street features intersected by all the line barriers exceeds 500.
- polygonBarrierLayer—An error will occur if the number of street features intersected by all the polygon barriers exceeds 2000.
- An error will occur if the tool takes more than 60 minutes to run when using travel modes. If this error occurs, rerun the analysis with fewer input features.
Request Parameters
Parameter | Details | |
---|---|---|
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 one of the following:
Examples:
| |
destinationsLayer (Required) | Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:
Examples:
| |
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 will be used as the 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 must specify the JSON object containing the settings for a travel mode supported by your organization. To get a list of supported travel modes, run the GetTravelModes operation from the Utilities service. When using a travel mode for the measurementType parameter, use a JSON object representing travel mode settings for the value. When you use the GetTravelModes operation from the Utilities service, the result is a string representing the travel mode JSON. You must convert this string to a valid JSON object using the API and pass the JSON object as the value for the measurementType parameter. For example, the following is a string representing the Walking Time travel mode as returned by the GetTravelModes operation:
Convert the value above to a valid JSON object and pass it as the value for the measurementType parameter. measurementType=
| |
originsLayerRouteIDField | Specify the field in the origins layer containing the IDs that pair origins with destinations.
| |
destinationsLayerRouteIDField | Specify the field in the destinations layer containing the IDs that pair origins with destinations.
| |
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:
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 4 hours and references predictive data extending 4 hours into the future. If the time and date you specify for this parameter is outside the 8-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:
Syntax: The number of milliseconds since the Unix epoch (January 1, 1970). Examples:
| |
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 | |
includeRouteLayers | When includeRouteLayers is set to true, each route from the result is also saved as a route layer item. A route layer includes all the information for a particular route, such as the stops assigned to the route as well as the travel directions. Creating route layers is useful if you want to share individual routes with other members in your organization. The route layers use the output feature service name provided in the outputName parameter as a prefix, and the route name generated as part of the analysis is added to create a unique name for each route layer. Caution:Route layers cannot be created when the output is a feature collection. The task will produce an error if an outputName value is not specified (which indicates feature collection output) and includeRouteLayers is set to true. The maximum number of route layers that can be created is 1,000. If the result contains more than 1,000 routes and includeRouteLayers is set to true, the task will only create the output feature service. | |
pointBarrierLayer | Specify one or more point features that act as temporary restrictions (barriers) when traveling on the underlying streets. A point barrier can model a fallen tree, an accident, a downed electrical line, or anything that completely blocks traffic at a specific position along the street. Travel is permitted on the street but not through the barrier. Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:
Examples:
| |
lineBarrierLayer | Specify one or more line features that prohibit travel anywhere the lines intersect the streets. A line barrier prohibits travel anywhere the barrier intersects the streets. For example, a parade or protest that blocks traffic across several street segments can be modeled with a line barrier. Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:
Examples:
| |
polygonBarrierLayer | Specify one or more polygon features that completely restrict travel on the streets intersected by the polygons. One use of this type of barrier is to model floods covering areas of the street network and making road travel there impossible. Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:
Examples:
| |
routeShape | Specify the shape of the route that connects each origin to it's destination when using a travel mode. Values: FollowStreets | StraightLine Default: FollowStreets
The best route between an origin and it's matched destination is always calculated based on the travel mode, regardless of which route shape is chosen. | |
outputName | If provided, the task will create a feature service of the results. You define the name of the service. If an outputName value is not provided, the task will return a feature collection. Syntax: Syntax: | |
context | Context contains additional settings that affect task execution. For Connect Origins to Destinations, there are two settings.
| |
f | The response format. The default response format is html. Values: html | json |
Response
When you submit a request, the service assigns a unique job ID for the transaction.
{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}
After the initial
request is submitted, you can use the
jobId to periodically check the status of the job and messages as described in the topic Checking job status.
Once the job has successfully completed, you use
the jobId to retrieve the results. To track the status, you can make a request of the following form:http://<analysis url>/ConnectOriginsToDestinations/jobs/<jobId>
Accessing results
When the status of the job request is esriJobSucceded, you can access the results of the analysis by making a request of the following form. http://<analysis url>/ConnectOriginsToDestinations/jobs/<jobId>/results/routesLayer?token=<your token>&f=json
Parameter | Description |
---|---|
routesLayer | The output layer containing the routes that connect origins to destinations. 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.
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:
|
unassignedOriginsLayer | The input origins that couldn't be included in the solution. Example:
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.
Fields in the output:
|
unassignedDestinationsLayer | The input destinations that couldn't be included in the solution. Example:
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.
Fields in the output:
|