Build Enrichment Layer

The Build Enrichment Layer task works with one or more layers of point, line, or polygon features. The tool generates square or hexagonal bins and compiles information about each input layer into each bin. For each input layer this information can include:

  • Distance to Nearest— The distance from each bin to the nearest feature.
  • Attribute of Nearest— An attribute value of the feature nearest to each bin.
  • Attribute Summary of Related— A statistical summary of all features within searchDistance of each bin.

Only the attributes that you specify in enrichmentAttributes will be included in the result layer. These attributes can help you understand the proximity of your data throughout the extent of your analysis. They can help you visualize answers to questions like:

  • Given multiple layers of public transportation infrastructure, where in the city is least accessible by public transportation?
  • Given layers of lakes and rivers, what is the name of the water body closest to each location in the US?
  • Given a layer of household income, where in the US is the variation of income in the surrounding 50 miles the largest?

The result of Build Enrichment Layer can also be used for enrichment in prediction and classification workflows. The tool allows you to calculate and compile information from many different data sources into single spatially-continuous layer in one step, reducing the amount of effort required to train prediction and classification models.

Request URL

http://<analysis url>/BuildEnrichmentLayer/submitJob

Request parameters

ParameterDescription

binSize

(Required)

The distance for the bins of type binType in the output polygon layer. enrichmentAttributes will be calculated at the center of each bin. 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.

REST web example: 108.3

REST scripting example: "binSize" : 100

binSizeUnit

(Required)

The distance unit for the bins that will be used to calculate enrichmentAttributes.

Values: Meters | Kilometers | Feet | Miles | NauticalMiles | Yards

REST web example: Meters

REST scripting example: "binSizeUnit" : "Miles"

binType

(Required)

The type of bin that will be generated. Bin options are the following:

  • Hexagon.
  • Square—This is the default.

REST web example: Hexagon

REST scripting example: "binType" : "Hexagon"

Note:

enrichmentAttributes

(Required)

A JSON array containing objects that describe the input layers and the attributes that will be calculated for each layer.

Syntax:

enrichmentAttributes syntax

[
    {
        "layer":{
            "url": "<url>",
            "filter": "<filter>"
        }
        "attributes":[
            {
                "type":"DistanceToNearest",
                "outFieldName":"<output field name>",
                "searchDistance":"<distance>",
                "filter":"<filter>"
            },
            {
                "type":"AttributeOfNearest",
                "outFieldName":"<output field name>",
                "attributeField":"<field name>",
                "searchDistance":"<distance>",
                "filter":"<filter>"
            },
            {
                "type":"AttributeSummaryOfRelated",
                "outFieldName":"<output field name>",
                "statisticType":"<statistic type>",
                "statisticField":"<field name>",
                "searchDistance":"<distance>",
                "filter":"<filter>"
            },
            ...
        ]
    },
    ...
]

layer follows the same formatting as described in the Feature Input topic. This can be one of the following:

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

attributes is an array of JSON objects that describe the attributes you would like to include in the result layer. The array must contain at least one attribute for each layer.

type can be one of the following attribute types:

  • DistanceToNearest
  • AttributeOfNearest
  • AttributeSummaryOfRelated
Each type must be configured with a unique set of parameters:
  • outFieldName is the name of the field that will be created in the result layer to store an attribute. This is required.
  • searchDistance is a string containing a distance and unit. For DistanceToNearest and AttributeOfNearest, searchDistance is required and is the maximum distance that the tool will search from the center of each bin to find a feature in the layer. If no feature is within the distance, null is returned. For AttributeSummaryOfRelated, searchDistance is optional and is the radius of a circular neighborhood surrounding each bin. All features that intersect this neighborhood will be used to calculate statisticType. If searchDistance is not included only features that intersect a bin will be used to calculate statisticType.
  • attributeField is required by AttributeOfNearest and is the name of a field in the input layer. The value of this field in the closest feature to each bin will be included in the result layer.
  • statisticField is required by AttributeSummaryOfRelated and is the name of a field in the input layer. This field's values will be used to calculate statisticType.
  • statisticType is required by AttributeSummaryOfRelated and is one of the following when statisticField is a numeric field:
    • Count—Totals the number of features near or intersecting each bin.
    • Sum—Adds the total value of all features near or intersecting each bin.
    • Mean—Calculates the average of all features near or intersecting each bin.
    • Min—Finds the smallest value of all features near or intersecting each bin.
    • Max—Finds the largest value of all features near or intersecting each bin.
    • Range—Finds the difference between Min and Max.
    • Stddev—Finds the standard deviation of all features near or intersecting each bin.
    • Var—Finds the variance of all features near or intersecting each bin.
    statisticType is one of the following when statisticField is a string field:
    • Count—Totals the number of strings for all features near or intersecting each bin.
    • Any—Returns a sample string of all features near or intersecting each bin.
  • filter is optional for all attribute types and is formatted, as described in the Feature Input topic.

In the REST web example for enrichmentAttributes shown below, two attributes are calculated for layer hurricaneTrack. distance_to_nearest_hurricane is the distance from each bin center to the nearest feature where type = "hurricane" and rating_of_nearest_hurricane is the value of field storm_rating in the nearest feature to each bin center. An attribute called mean_wind_speed is also calculated for layer weatherPoints and is the mean value of field wind_speed in all features within a 20 mile radius of each bin center. All three attributes are stored in attribute table of the output layer.

REST web example for enrichmentAttributes

[
    {
        "layer":{
            "url":"http://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0"
        },
        "attributes":[
            {
                "type":"DistanceToNearest",
                "outFieldName":"distance_to_nearest_hurricane",
                "searchDistance":"100 miles",
                "filter":"type = "hurricane""
            },
            {
                "type":"AttributeOfNearest",
                "outFieldName":"rating_of_nearest_hurricane",
                "attributeField":"storm_rating",
                "searchDistance":"100 miles",
            }
        ]
    },
    {
        "layer":{
            "url":"http://myportal.domain.com/server/rest/services/Hosted/weatherPoints/FeatureServer/0"
        },
        "attributes":[
            {
                "type":"AttributeSummaryOfRelated",
                "outFieldName":"mean_wind_speed",
                "statisticType":"mean",
                "statisticField":"wind_speed",
                "searchDistance":"20 miles",
            }
        ]
    }
]

In the REST scripting example for enrichmentAttributes shown below, two attributes are calculated for layer hurricaneTrack. distance_to_nearest_hurricane is the distance from each bin center to the nearest feature where type = "hurricane" and distance_to_nearest_trop_storm is that where type = "tropical storm". Both are stored in the attribute table of the output layer.

REST scripting example for enrichmentAttributes

"enrichmentAttributes":"[
    {
        "layer":{
            "url":"http://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0"
        },
        "attributes":[
            {
                "type":"DistanceToNearest",
                "outFieldName":"distance_to_nearest_hurricane",
                "searchDistance":"100 miles",
                "filter":"type = "hurricane""
            },
            {
                "type":"DistanceToNearest",
                "outFieldName":"distance_to_nearest_trop_storm",
                "searchDistance":"100 miles",
                "filter":"type = "tropical storm""
               
            }
        ]
    }
]"

outputName

(Required)

The task will create a feature service of the results. You define the name of the service.

REST web example: myOutput

REST scripting example: "outputName" : "myOutput"

context

Context contains additional settings that affect task execution. For this task, there are four settings:

  • Extent (extent)—A bounding box that defines the analysis area. Only those features that intersect the bounding box will be analyzed.
  • Processing spatial reference (processSR)—The features will be projected into this coordinate system for analysis.
  • Output spatial reference (outSR)—The features will be projected into this coordinate system after the analysis to be saved. The output spatial reference for the spatiotemporal big data store is always WGS84.
  • Data store (dataStore)—Results will be saved to the specified data store. The default is the spatiotemporal big data store.

Syntax:
{
"extent" : {extent},
"processSR" : {spatial reference},
"outSR" : {spatial reference},
"dataStore":{data store}
}

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 jobId to periodically check the status of the job and messages as described in Checking job status. Once the job has successfully completed, use the jobId to retrieve the results. To track the status, you can make a request of the following form:

Accessing results

When the status of the job request is esriJobSucceeded, you can access the results of the analysis by making a request of the following form:

http://<analysis url>/BuildEnrichmentLayer/jobs/<jobId>/results/output?token=<your token>&f=json

ParameterDescription

output

output will always contain polygon features. The number of resulting polygons is based on binSize, enrichmentAttributes, and the extent of the input data.

The layer will only contain the attributes specified in enrichmentAttributes.

Request example:
{"url": 
"http://<analysis url>/BuildEnrichmentLayer/jobs/<jobId>/results/output"}

The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter provided in the initial request. The value contains the URL of the feature service layer.

{
"paramName":"output", 
"dataType":"GPRecordSet",
"value":{"url":"<hosted featureservice layer url>"}
}

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