AggregatePoints

pointLayer

feature | 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:

• A URL to a feature service layer with an optional filter to select specific features
• A feature collection

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

polygonLayer

feature | sometimes required

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:

• A URL to a feature service layer with an optional filter to select specific features
• A feature collection

keepBoundariesWithNoPoints

Boolean | optional

Default value: true

Accepted values: true | false

Specifies whether the polygons that have no points within them will be returned in the output. If true, all generated bins or input polygons will be returned, including those that do not overlap input points. If false, bins or polygons with no summarized points will be removed from the output.

summaryFields

string | optional

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 one of the numeric or date fields in the input pointLayer parameter.

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

string | optional

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 groupByField is provided, two results are created: the result layer and a related groupSummary table containing the statistics.

minorityMajority

Boolean | optional

Default value: false

Accepted values: true | false

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 aggregatedLayer prefixed with Majority_ and Minority_.

percentPoints

Boolean | optional

Default value: false

Accepted values: true | false

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 aggregatedLayer containing the percentages of the minority and majority attribute values within each group.

outputName

string | optional

The name of the output layer.

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:

1
2
3
4
5
{
  "serviceProperties": {
		"name": "featureServiceName"
  }
}

You can overwrite an existing feature service by providing the itemId, serviceURL, or name value of the existing feature service and setting the overwrite property to true. Including the serviceProperties parameter is optional. As described in the Feature output topic, you must either be the owner of the feature service or have administrative privileges to perform the overwrite.

1
2
3
4
5
6
{
  "itemProperties": {
		"itemId": "52d34e7598e7484188228xxxxxx",
		"overwrite": true
  }
}

1
2
3
4
5
6
7
8
9
{
  "serviceProperties": {
		"serviceURL": "https://organization.example.com/<context>/rest/services/Hosted/
		FeatureServiceName/FeatureServer"
  },
  "itemProperties": {
		"overwrite": true
  }
}

1
2
3
4
5
6
7
8
{
  "serviceProperties": {
		"name": "featureServiceName"
  },
  "itemProperties": {
		"overwrite": true
  }
}

context

string | optional

The Context parameter contains the following additional settings that affect task operation:

• Extent (extent)—A bounding box that defines the analysis area. Only input features that intersect the bounding box will be analyzed.
• Output spatial reference (outSR)—The output features will be projected into the output spatial reference.

Syntax:

1
2
3
4
{
"extent" : {extent},
"outSR" : {spatial reference}
}

binType

string | optional

Default value: Square

Accepted values: Hexagon | Square

The type of bin that will be generated and points will be aggregated into. Bin options are as follows:

• Hexagon
• Square—This is the default.

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

double | sometimes required

The distance used to calculate the size of the bins specified in the binType parameter that the pointLayer will be aggregated into. This parameter is required if binType is used.

Example: "binSize" : 100

binSizeUnit

string | sometimes required

Default value: Meters

Accepted values: Meters | Kilometers | Feet | Miles | NauticalMiles | Yards

The linear unit to be used with the distance value specified in binSize. This parameter is required if binType is used.

Example: "binSizeUnit" : "Miles"

f

string | optional

Default value: html

Accepted values: html | json

The response format.

aggregatedLayer

features | required

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.

Fields

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.

Request example

1
{"url":"https://<analysis url>/AggregatePoints/jobs/<jobId>/results/aggregatedLayer"}

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.

1
2
3
4
5
{
  "paramName":"aggregatedLayer",
  "dataType":"GPString",
  "value":{"url":"<hosted feature service layer url>"}
}

1
2
3
4
5
{
  "paramName":"aggregatedLayer",
  "dataType":"GPString",
  "value":{"layerDefinition": {}, "featureSet": {}  }
}

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

groupSummary

table | optional

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.

Fields

The output table will have the following fields:

• Join_ID—The object ID of the input polygonLayer.
• 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 specify "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

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

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.

1
2
3
4
5
{
  "paramName":"groupSummary",
  "dataType":"GPString",
  "value":{"url":"<hosted feature service table url>"}
}

1
2
3
4
5
{
  "paramName":"groupSummary",
  "dataType":"GPString",
  "value":{"layerDefinition": {}, "featureSet": {}  }
}

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