The Aggregate Points task works with a layer of point features and a layer of polygon features or bins. It first identifies which points fall within each polygon's area. After identifying this point-in-polygon spatial relationship, statistics for all points in the polygon are calculated and assigned to the area. The most basic statistic is the number of points within the polygon (count), but you can get other statistics as well.
For example, if the points represent coffee shops and each point has a TOTAL_SALES attribute, you can get statistics such as the sum of all sales within the polygon, the minimum or maximum TOTAL_SALESvalue, or the standard deviation of all sales within the polygon.
Request URL
http://<analysis url>/AggregatePoints/submitJob
Request parameters
Parameter | Description |
---|---|
pointLayer (Required) | The point features that will be aggregated into polygons in the polygonLayer parameter or the specified bins. Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:
Examples:
|
polygonLayer | The polygon features (areas) into which the input points will be aggregated. The polygonLayer parameter is required unless a value for the binType parameter is specified. Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:
|
keepBoundariesWithNoPoints | A Boolean value that specifies whether the polygons that have no points within them will be returned in the output. The default is true. Values: true | false |
summaryFields | A list of field names and statistical summary types that will be calculated for all points within each polygon. The count of points within each polygon is always returned. Syntax: ["fieldName summaryType","fieldName summaryType", ...] fieldName is the name of one of the numeric fields in the input point layer. summaryType is one of the following:
Example: "summaryFields": ["Annual_Sales Sum", "Annual_Sales Mean"] |
groupByField | A 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. Example: "groupByField": "Crime_type" When a groupByField field is provided, two results are created: the result layer and a related groupBySummary table containing the statistics. |
minorityMajority | This Boolean parameter is applicable only when a groupByField value is specified. If true, the minority (least dominant) or the majority (most dominant) attribute values for each group field within each boundary are calculated. Two new fields are added to the aggregatedLayer prefixed with Majority_ and Minority_. The default is false. Values: true | false |
percentPoints | This Boolean parameter is applicable only when a groupByField value is specified. If true, the percentage count of points for each unique groupByField value is calculated. A new field is added to the groupSummary output table containing the percentages of each attribute value within each group. If minorityMajority is true, two additional fields are added to the aggregatedLayer containing the percentages of the minority and majority attribute values within each group. |
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 | The Context parameter contains the following additional settings that affect task operation:
Syntax:
|
binType | The type of bin that will be generated and points will be aggregated into. Bin options are as follows:
Example: "binType" : "Hexagon" When generating bins, for Square, the number and units specified determine the height and length of the square. For Hexagon, the number and units specified determine the distance between parallel sides. Either binType or polygonLayer must be specified. If binType is chosen, binSize and binSizeUnit specifying the size of the bins must be included. |
binSize (Required if binType is used) | The distance used to calculate the size of the bins specified in the binType parameter that the pointLayer will be aggregated into. Example: "binSize" : 100 |
binSizeUnit (Required if binType is used) | The linear unit to be used with the distance value specified in binSize. Values: Meters | Kilometers | Feet | Miles | NauticalMiles | Yards The default is Meters. Example: "binSizeUnit" : "Miles" |
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 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>/AggregatePoints/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>/AggregatePoints/jobs/<jobId>/results/<output parameter name>?token=<your token>&f=json
Parameter | Description |
---|---|
aggregatedLayer |
aggregatedLayer will always contain polygon features. It may have the same number of or fewer polygon features than the input polygon layer, based on the value of keepPolygonsWithNoPoints. The layer will inherit all the attributes of the input polygon layer and will have a Point_Count attribute that is the number of points enclosed by the polygon. If a summaryFields parameter value is specified in the task request, the layer will have additional attributes for each requested summary. For example, if you request the following: "summaryFields" :["Annual_Sales Sum", "Annual_Sales Mean"] The result polygon features will have two attributes, Sum_Annual_Sales and Mean_Annual_Sales, to contain the calculated values. The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter value provided in the initial request.
See Feature output for more information about how the result layer or collection is accessed. |
groupSummary | If the groupByField parameter is specified, an optional group summary table is created. The group summary table provides the count of points and other summary fields for each group of points for each polygon boundaries in the polygon layer. Tables are a subset of features; that is, they contain attributes but no geometry. The output table will have the following fields:
Request example:
The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter value provided in the initial request.
See Feature output for more information about how the group summary table is accessed. |