Aggregate points

An aggregate analysis resulting in a new layer that contains the total count of breweries within each USA county.

What is an aggregate analysis?

An aggregate analysis is the process of finding which points fall inside polygons using a point-in-polygon spatial relationship. Feature geometry and attribute statistics are also generated for the number of points in each polygon. To execute the analysis, use the spatial analysis service and the AggregatePoints operation.

aggregate points

Real-world examples of this analysis include the following:

  • Simplifying the visualization of high-density point data.
  • Aggregating tornado data into state and county boundaries and normalize by population to find the areas most affected by tornadoes.
  • Aggregate construction permit points in each zipcode to predict future growth.

How to perform an aggregate analysis

The general steps to performing an aggregate points analysis are as follows:

  1. Review the parameters for the AggregatePoints operation.
  2. Send a request to get the spatial analysis service URL.
  3. Execute a job request with the following URL and parameters:
    • URL: https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/AggregatePoints/submitJob
    • Parameters:
      • pointLayer: The point features that will be aggregated into the polygons in the polygonLayer.
      • polygonLayer: The polygon features into which the input points will be aggregated.
      • outputName: A string representing the name of the hosted feature layer to reutrn with the results.
  4. Check the status.
  5. 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
 
1
http://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/AggregatePoints/submitJob?

Required parameters

Name
Description
Examples
fThe format of the data returnedf=json f=pjson
tokenAn OAuth 2.0 access token. Learn how to get an access token in Security and authentication.token=<ACCESS_TOKEN>
pointLayerThe point features aggregated into the polygons in the polygonLayer.{"url": <SERVICE_URL>, "filter": <where clause>}

{"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

Key parameters

NameDescriptionExamples
polygonLayerThe polygon features (areas) into which the input points will be aggregated.{"url": <feature service layer url>, "filter": <where clause>}

{"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}
keepBoundariesWithNoPointsA Boolean value that specifies whether the polygons that have no points within them should be returned in the output. The default is true.true | false
summaryFieldsA list of field names and statistical summary type that you want to calculate for all points within each polygon. Note that the count of points within each polygon is always returned."summaryFields": ["Annual_Sales Sum", "Annual_Sales Mean"]
groupByFieldA field name in the pointLayer. Points that have the same value for the group by field will have their own counts and summary field statistics. You can create statistical groups using an attribute in the analysis layer. For example, if you are aggregating crimes to neighborhood boundaries, you may have a Crime_type attribute with five crime types. Each unique crime type forms a group, and the statistics you choose will be calculated for each unique value of Crime_type."groupByField": "Crime_type"
outputNameA 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>"}}

Example

Find the number of breweries in counties

This example uses the AggregatePoints operation to summarize Brewery locations in USA counties. The results can be visualized by rendering the layer based on the calculated count of breweries in each county.

In the analysis, the polygonLayer value is the USA Counties hosted feature layer provided by the ArcGIS Living Atlas of the World.

The pointLayer value is a hosted feature layer for brewery locations across the United States. The groupField parameter is set to use the brewery_type field from the pointLayer so statistics will be calculated for each unique type.

Aggregate points analysis showing the number of breweries in each county.

APIs

ArcGIS REST JSArcGIS REST JSArcGIS API for Python
Expand
Use dark colors for code blocksCopy
                                                              
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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
  const operationUrl = `${analysisUrl}/AggregatePoints/submitJob`;

  const params = {
    polygonLayer: {
      url:
        "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Find_Locations_in_USA_Counties_Generalized_CONUS/FeatureServer/0",
    },
    pointLayer: {
      url:
        "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/obdb/FeatureServer/0",
    },
    keepBoundariesWithNoPoints: false,
    groupByField: "brewery_type",
    minorityMajority: true,
    percentPoints: true,
    outputName: {
      serviceProperties: {
        name: "Aggregate points results", //Outputs results as a hosted feature serivce.
      },
    }
  };

  const jobReq = await Job.submitJob({
    url: operationUrl,
    params: params,
    authentication: auth,
  });

  // listen to the status event to get updates every time the job status is checked.
  jobReq.on(JOB_STATUSES.Status, jobInfo => {
    console.log(jobInfo.status)
  });

  // get all the results, this will start monitoring and trigger events
  const jobResp = await jobReq.getAllResults();

Service requests

Request
HTTPHTTPcURL
Use dark colors for code blocksCopy
     
1
2
3
4
5
POST arcgis.com/sharing/rest/portals/self HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>
Response (JSON)
Use dark colors for code blocksCopy
           
1
2
3
4
5
6
7
8
9
10
11
{
  "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"
    }
  }
}