Summarize nearby

A nearby analysis resulting in a new layer with parks within 300 feet from a cafe.

What is a nearby analysis?

A nearby analysis is the process of finding features within a specified distance of other feature data. To execute the analysis, use the spatial analysis service and the SummarizeNearby operation.

The distance measure can be a straight line or defined by a trave mode. Feature geometry and attribute statistics are also generated.

Use the Summarize nearby operation to calculate statistics on point, polyline, or polygon features within close proximity of another hosted feature layer.

For example, using Summarize nearby, you could:

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.
Calculate school walk zones.

There are limits to the 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)
An error will occur if the operation takes more than 60 minutes to execute when using travel modes. If this error occurs, try rerunning the analysis with fewer input features.

How to perform a nearby analysis

The general steps to performing a summarize nearby analysis are as follows:

Review the parameters for the SummarizeNearby operation.
Send a request to get the spatial analysis service URL.
Execute a job request with the following URL and parameters:
- URL: https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/SummarizeNearby/submitJob
- Parameters:
  - sumNearbyLayer: The feature data from which distances will be measured to features in the summaryLayer.
  - summaryLayer: Feature data that are within the specified distance to features in the sumNearbyLayer.
  - outputName: The name of the resulting feature layer.
Check the status.
Get the output layer results.

To see examples using ArcGIS API for Python, ArcGIS REST JS, and the ArcGIS REST API, go to Examples below.

URL Request

Use dark colors for code blocksCopy
http://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/SummarizeNearby/submitJob

Required parameters

Name	Description	Examples
`f`	The format of the data returned	`f=json` `f=pjson`
`token`	An OAuth 2.0 access token.	`token=<ACCESS_TOKEN>`
`sumNearbyLayer`	Point, line, or polygon features from which distances will be measured to features in the `summaryLayer`.	`{"url": <SERVICE_URL>, "filter": <where clause>}` `{"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}`
`summaryLayer`	Point, line, or polygon features. Features in this layer that are within the specified distance to features in the `sumNearbyLayer` will be summarized.	`{"url": <SERVICE_URL>, "filter": <where clause>}` `{"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}`

Key parameters

Name	Description	Examples
`nearType`	Defines what type 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`. For details about supported travel modes see the GetTravelModes operation from the Utilities service.	`"nearType": "StraightLine"`
`distances`	A list 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 are supplied by the `units` parameter.	`"distances": [4.0]`
`units`	If `nearType` is `StraightLine` or a distance-based travel mode, this is the linear unit to be used with the distance values specified in distances. If `nearType` is a time-based travel mode, then units are time based	"units": "Miles" "Units": "Minutes"
`returnBoundaries`	If true, the resultLayer will contain areas defined by the specified `nearType`. For example, if using a `StraightLine` value of 5 miles, the resultLayer will contain areas with a 5-mile radius around the input `sumNearbyLayer` features.	`true
`outputName`	A string representing the name of the hosted feature layer to return with the results. NOTE: If you do not include this parameter, the results are returned as a feature collection (JSON).	`{"serviceProperties": {"name": "<SERVICE_NAME>"}}`

Privileges

Example

Find cafes near parks

In this example, Summarize nearby is used to find parks that have cafes that are within 300 ft.

In this analysis, the sumNearbyLayer value is a hosted feature layer of parks polygons. The summaryLayer value is a hosted feature layer of Sidewalk cafes points. The nearType parameter is set to StraightLine with distance and units equal to 300 Feet.

Summarize nearby analysis reveals parks thave have cafes within 300 ft.

APIs

ArcGIS API for Python

ArcGIS REST JS

Expand

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
nearLayer = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/obdb/FeatureServer/0"
summaryLayer = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Enriched_Portland_Neighborhoods/FeatureServer/0"

results = summarize_nearby(
    summary_layer=summaryLayer,
    sum_nearby_layer=nearLayer,
    near_type="StraightLine",
    distances=[0.25],
    units="Miles",
    return_boundaries=False,
    minorityMajority=True,
    percent_shape=True,
    group_by_field="brewery_type",
    #Outputs results as a hosted feature layer.
    output_name="Summarize nearby results"
)

print(f"summarize result item created {results.itemid}")

Go to API Reference

Service requests

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST arcgis.com/sharing/rest/portals/self HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>
Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "helperServices": {
    // Other parameters
    "analysis": {
      "url": "https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer"
    },
    "geoenrichment": {
      "url": "https://geoenrich.arcgis.com/arcgis/rest/services/World/GeoenrichmentServer"
    }
  }
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/SummarizeNearby/submitJob HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>
&sumNearbyLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/obdb/FeatureServer/0"}
&summaryLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Enriched_Portland_Neighborhoods/FeatureServer/0"}
&nearType=StraightLine
&distances=[0.25]
&units=Miles
&returnBoundaries=false
&outputName={"serviceProperties":{"name": "Summarize nearby results"}}
&sumShape=true
&groupByField=brewery_type
&minorityMajority=true

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy

{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSubmitted",
  "results": {},
  "inputs": {},
  "messages": []
}
Expand

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/SummarizeNearby/jobs/<JOB_ID> HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Run in Postman

Response (JSON)

Expand
Use dark colors for code blocksCopy
{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSucceeded",
  "results": {
    "resultLayer": {
      "paramUrl": "results/resultLayer"
    },
    "groupBySummary": {
      "paramUrl": "results/groupBySummary"
    }
  },
  "inputs": {},
  "messages": []
}
Expand

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/SummarizeNearby/jobs/<JOB_ID>/results/resultLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Run in Postman

Response (JSON)

Expand
Use dark colors for code blocksCopy
{
  "paramName": "resultLayer",
  "dataType": "GPString",
  "value": {
    "url": "<url>",
    "itemId": "<itemid>"
  }
}