Summarize Nearby

Summarize Nearby

The Summarize Nearby task finds features that are within a specified distance of features in the input layer. Distance can be measured as a straight-line distance or by a specified travel mode. Statistics are then calculated for the nearby features. For example:

  • Calculate the total population within five minutes of driving time of a proposed new store location.
  • Calculate the number of freeway access ramps within a one-mile driving distance of a proposed new store location to use as a measure of store accessibility.

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 summarize nearby features using one of the available travel modes, you also need to be granted the Network Analysis privilege.

Request URL

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

Limits

There are limits to number of features and distance when nearType is set to a travel mode other than "StraightLine".

  • sumNearbyLayer—maximum 1,000 features
  • distance—maximum 300 minutes or 482.80 kilometers (300 miles)

Request Parameters

ParameterDescription

sumNearbyLayer

(Required)

Point, line, or polygon features from which distances will be measured to features in the summaryLayer.

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

summaryLayer

(Required)

Point, line, or polygon features. Features in this layer that are within the specified distance to features in the sumNearbyLayer will be summarized.

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

nearType

(Required)

Defines what kind of distance measurement you want to use: straight-line distance, or by measuring travel time or travel distance along a street network using various modes of transportation known as travel modes. The default is StraightLine.

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 nearType, 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 nearType 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 bufferType parameter

nearType=

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

Example:

  • "nearType": "StraightLine"

distances

(Required)

An array of double values that defines the search distance (for StraightLine and distance based travel modes) or time (for time based travel modes). You can enter a single distance value or multiple values, separating each value with a space. Features that are within (or equal to) the distances you enter will be summarized. The units of the distance values is supplied by the units parameter.

Examples:

  • "distances": [4.0]
  • "distances": [4.0, 5.0, 6.0]

units

If nearType is StraightLine or a distance-based travel mode, this is the linear unit to be used with the distance value(s) specified in distances.

Values: Meters | Kilometers | Feet | Yards | Miles

If nearType is a time based travel mode, the following values can be used as units:

Values: Seconds | Minutes | Hours

The default is Meters

Example:

  • "units": "Miles"

timeOfDay

Specify whether travel times should consider traffic conditions. To use traffic in the analysis, set nearType 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 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:

  • This parameter is ignored when nearType 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 sumNearbyLayer 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

returnBoundaries

If true, the resultLayer will contain areas defined by the specified nearType. For example, if using StraightLine of 5 miles, the resultLayer will contain areas with a 5 mile radius around the input sumNearbyLayer features.

If false, the resultLayer will contain the same features as the sumNearbyLayerlayer.

The default is true.

Values: true | false

sumShape

A Boolean value that instructs the task to calculate statistics based on shape type of the summaryLayer, such as the length of lines or areas of polygons of the summaryLayer within each polygon in sumWithinLayer. The default is true.

Values: true | false

shapeUnits

(Required if sumShape is true)

If sumShape is true, you must specify the units of the shape summary.

Values:

  • When summaryLayer contains polygons: Acres | Hectares | SquareMeters | SquareKilometers | SquareFeet | SquareYards | SquareMiles
  • When summaryLayer contains lines: Meters | Kilometers | Feet | Yards | Miles

summaryFields

A list of field names and statistical summary type that you wish to calculate for all nearby features.

Syntax: ["fieldName summaryType","fieldName summaryType", ...]

fieldName is the name of one of the numeric fields found in the summaryLayer.

summaryType is one of the following:

  • Sum—Adds the total value of all the features in each polygon
  • Mean—Calculates the average of all the features in each polygon.
  • Min—Finds the smallest value of all the features in each polygon.
  • Max—Finds the largest value of all the features in each polygon.
  • Stddev—Finds the standard deviation of all the features in each polygon.

Example:

  • "summaryFields": ["Lot_Value Sum", "Lot_Value Mean"]

groupByField

This is a field of the summaryLayer features that you can use to calculate statistics separately for each unique attribute value. For example, suppose the summaryLayer contains point locations of businesses that store hazardous materials, and one of the fields is HazardClass containing codes that describe the type of hazardous material stored. To calculate summaries by each unique value of HazardClass, use HazardClass as the groupByField field.

Example:

  • "groupByField": "HazardClass"

minorityMajority

This boolean parameter is applicable only when a groupByField is specified. If true, the minority (least dominant) or the majority (most dominant) attribute values for each group field within each nearby area are calculated. Two new fields are added to the resultLayer prefixed with Majority_ and Minority_.

The default is false.

Values: true | false

percentShape

This Boolean parameter is applicable only when a groupByField is specified. If set to true, the percentage of each unique groupByField value is calculated for each sumNearbyLayer feature. The default is false.

Values: true | false

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 Summarize Nearby, there are two settings.

  1. Extent (extent)—a bounding box that defines the analysis area. Only those features in the sumNearbyLayer and summaryLayer that intersect the bounding box will be analyzed.
  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>/SummarizeNearby/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>/SummarizeNearby/jobs/<jobId>/results/<output parameter name>?token=<your token>&f=json

ParameterDescription

resultLayer

Example:
{"url": 
"http://<analysis url>/SummarizeNearby/jobs/<jobId>/results/resultLayer"}

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

  • If outputName was provided, value contains the url to the feature service layer.

    {
    "paramName":"resultLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }

  • If outputName was not provided, value contains a layer definition and feature set.

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

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

groupBySummary

If a groupByField field was provided as input, the result will have a groupBySummary table that contains the caclulated statistics for each unique group. Tables are simply a subset of features; that is, they contain attributes but no geometry.

Example:
{"url": 
"http://<analysis url>/SummarizeNearby/jobs/<jobId>/results/groupBySummary"}

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

  • If outputName was provided, value contains the url to the feature service layer.

    {
    "paramName":"groupBySummary", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }

  • If outputName was not provided, value contains a layer definition and feature set.

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

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