Aggregate Points

Aggregate Points

The Aggregate Points task works with a layer of point features and a layer of polygon features. It first figures out which points fall within each polygon's area. After determining this point-in-polygon spatial relationship, statistics about all points in the polygon are calculated and assigned to the area. The most basic statistic is the count of the number of points within the polygon, but you can get other statistics as well.

For example, if your points represented coffee shops and each point has a TOTAL_SALES attribute, you can get statistics like the sum of all TOTAL_SALES within the polygon, or 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

ParameterDescription

pointLayer

(Required)

The point features that will be aggregated into the polygons in the polygonLayer.

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

polygonLayer

(Required)

The polygon features (areas) into which the input points will be aggregated.

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.

keepBoundariesWithNoPoints

A Boolean value that specifies whether the polygons that have no points within them should be returned in the output. The default is true.

Values: true | false

summaryFields

A list of field names and statistical summary type that you wish to calculate for all points within each polygon. Note that 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 found in the input point layer.

summaryType is one of the following:

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

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 an attribute Crime_type with five different crime types. Each unique crime type forms a group, and the statistics you choose will be calculated for each unique value of Crime_type. When you choose a grouping attribute, two results are created: the result layer and a related table containing the statistics.

Example: "groupByField": "Crime_type"

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 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 is specified. If set to 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 istrue, 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 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 Aggregate Points, there are two settings.

  1. Extent (extent)—a bounding box that defines the analysis area. Only those points in the input pointLayer 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>/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

ParameterDescription

aggregatedLayer

aggregatedLayer will always contain polygon features. It may have the same or lesser number of polygon features as 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 which is the number of points that are enclosed by the polygon.

If a summaryFields parameter is specified in the task request, the layer will have additional attributes for each requested summary. For example, if you had requested

"summaryFields" :["Annual_Sales Sum", "Annual_Sales Mean"]

The result polygon features would have two attributes, Sum_Annual_Sales and Mean_Annual_Sales to contain the calculated values.

Request example:
{"url": 
"http://<analysis url>/AggregatePoints/jobs/<jobId>/results/aggregatedLayer"}

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":"aggregatedLayer", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice layer url>"}
    }
  • If outputName was not provided, value contains a feature collection.
    {
    "paramName":"aggregatedLayer",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {}  }
    }

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 simply a subset of features; that is, they contain attributes but no geometry.

The output table will have the following fields:

  • Join_ID—the object ID of the input polygonLayer.
  • The groupByField.
  • Point_Count_<groupByField name>—the count of points within the group.
  • Fields based on the summaryFields parameter in the task request. The summary attribute name will be of type <summary type>_<fieldname>. For example, if you specified "summaryFields": ["Annual_Sales Max"] in the task request a corresponding Max_Annual_Sales attribute will be included in the table to present the maximum annual sales for each group in each polygon area.

Request example:

{"url": 
"http://<analysis url>/AggregatePoints/jobs/<jobId>/results/groupSummary
"}

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":"groupSummary", 
    "dataType":"GPString",
    "value":{"url":"<hosted featureservice table url>"}
    }
  • If outputName was not provided, value contains a feature collection.
    {
    "paramName":"groupSummary",
    "dataType":"GPString",
    "value":{"layerDefinition": {}, "featureSet": {}  }
    }

See Feature Output for more information about how the group summary table is accessed.