Create Drive-Time Areas

Create Drive-Time Areas

The Create Drive-Time Areas task creates areas that can be reached within a given drive time or drive distance. It can help you answer questions such as:

  • How far can I drive from here in five minutes?
  • What areas are covered within a three-mile drive distance of my stores?
  • What areas are within four minutes of our fire stations?
Note:

This task is designed to provide a simple solution to the most common uses of drive-time areas. If you require additional flexibility to solve a more specialized problem, consider using either the Service Area Service with Asynchronous Execution or Service Area Service with Synchronous Execution instead. They provide options, for instance, to create more detailed polygons, specify travel towards the input points rather than away from them, and add barriers to block certain roads or areas.

Licensing

As described in the Get Started topic, in order to use any analysis task, the administrator of the organization needs to grant you certain basic privileges. To use Create Drive-Time Areas, you also need to be granted the Network Analysis privilege.

Limits

There are limits to the number of features and drive time or drive distance.

  • inputLayer—maximum 1,000 features
  • breakValues—maximum 300 minutes or 482.80 kilometers (300 miles)

Request URL

http://<analysis url>/CreateDriveTimeAreas/submitJob

Request Parameters

ParameterDetails

inputLayer

(Required)

The points around which travel areas based on a mode of transportation will be drawn.

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

travelMode

Specify the mode of transportation for the analysis.

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.

The value for the travelMode parameter 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 travelMode 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 travelMode parameter

travelMode=

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

breakValues

The size of the polygons to create. The units for breakValues is specified with the breakUnits parameter.

The numeric break value or values are passed in as an array of doubles. By setting many unique values in the array, polygons of different sizes are generated around each input location.

Examples:

  • "breakValues": [5.0]
  • "breakValues": [5.0, 10.0, 15.0]

breakUnits

The units of the breakValues parameter. The default is Minutes.

To create areas showing how far you can go along roads or walkways within a given time, specify a time unit. Alternatively, specify a distance unit to generate areas bounded by a maximum travel distance.

When the travelMode is time based, a time unit should be specified for the breakUnits. When the travelMode is distance based, a distance unit should be specified for the breakUnits

Values: Seconds | Minutes | Hours | Feet | Yards | Meters |Kilometers | Miles

Example:"breakUnits": "Minutes"

overlapPolicy

Determines how overlapping areas are processed.

Values: Overlap | Dissolve | Split

Overlap (default)

Overlap—Overlapping areas are kept. This is the default.

Dissolve

Dissolve—Overlapping areas are combined by break value. Because the areas are dissolved, use this option when you need to know the areas that can be reached within a given time or distance, but you don't need to know which input points are nearest.

Split

Split—Overlapping areas are split in the middle. Use this option when you need to know the one nearest input location to the covered area.

Example: "overlapPolicy": "Split"

timeOfDay

Specify whether travel times should consider traffic conditions. To use traffic in the analysis, To use traffic in the analysis, set travelMode to a travel mode object whose impedanceAttributeName property is set to TravelTime, set breakUnits to a time unit 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 input 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:

  • All points in inputLayer need to be in the same time zone when using traffic and setting overlapPolicy to split or dissolve.
  • This parameter is ignored when breakUnits is set to distance unit.
  • The time zone for timeOfDay can be UTC or the time zone or zones in which the points in inputLayer 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 or zones in which the input points are located. This option causes the analysis to have rolling start times across time zones.

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 points in the Eastern Time Zone to start at 9:00 a.m. Eastern Time and 9:00 a.m. Central Time for points in the Central Time Zone. (The start times are offset by an hour in real or UTC time.)

Input: timeOfDay is 9:00 a.m., 4 Jan. 1990 (631443600000 milliseconds), and timeZoneForTimeOfDay is set to GeoLocal

UTC:

The timeOfDay value refers to Coordinated Universal Time (UTC). The start times for all points are simultaneous, regardless of time zones.

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

Input: timeOfDay is 9:00 a.m., 4 Jan. 1990 (631443600000 milliseconds), and timeZoneForTimeOfDay is set to 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.

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

context

Context contains additional settings that affect task execution. For Create Drive-Time Ares, there are two settings:

  1. Extent (extent)—a bounding box that defines the analysis area. Only those features in the inputLayer that are within the bounding box will have driving areas created around them.
  2. Output Spatial Reference (outSR)—the output features will be projected into the output spatial reference.
Syntax:
{
"extent" : {extent}
"outSR" : {spatial reference}
}

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.

Syntax:
{
"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 retrive the results. To track the status, you can make a request of the following form:

http://<analysis url>/CreateDriveTimeAreas/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>/CreateDriveTimeAreas/jobs/<jobId>/results/driveTimeAreasLayer?token=<your token>&f=json

ParameterDescription

driveTimeAreasLayer

The output layer containing the areas that can be reached within the given driving time or driving distance from the points in the input layer.

Example:
{"url": 
"http://<analysis url>/CreateDriveTimeAreas/jobs/<jobId>/results/driveTimeAreasLayer"}

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":"driveTimeAreasLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }

  • If outputName was not provided, value contains a feature collection.

    {
    "paramName": "driveTimeAreasLayer",
    "dataType": "GPString",
    "value":{"layerDefinition": {}, "featureSet": {} }
    }

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

Discussion:

The result layer has the following attributes:

  • FacilityOID—A number that relates each drive-time area back to the unique identifier of the point around which the area was generated.
  • Name—The name of the drive-time area is the same as the name of the point location from which it was created followed by the from- and to-break values of the area.
  • FromBreak—The travel distance or travel time from which the area begins. This is normally zero, since most travel time polygons start from the input point location. However, non-zero values are present when you specify multiple break values, because all but the first output areas would start from one of the break values.
  • ToBreak—The travel distance or travel time at which the area ends. If the analysis includes multiple input break values, multiple ToBreakValues are included here but in different rows.