- URL:
- https://<geoanalytics-url>/BuildMultiVariableGrid
- Methods:
GET
- Version Introduced:
- 10.6.1
Description
The Build
operation works with one or more layers of point, line, or polygon features. The task generates a grid of square or hexagonal bins and compiles information about each input layer into each bin. For each input layer, this information can include the following variables:
Distance
—The distance from each bin to the nearest feature.To Nearest Attribute
—An attribute value of the feature nearest to each bin.Of Nearest Attribute
—A statistical summary of all features withinSummary Of Related search
of each bin.Distance
Only variables you specify in variable
will be included in the result layer. These variables can help you understand the proximity of your data throughout the extent of your analysis. The results can help you answer questions such as the following:
- Given multiple layers of public transportation infrastructure, what part of 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 United States?
- Given a layer of household income, where in the United States is the variation of income greatest in the surrounding 50 miles?
The result of Build
can also be used in prediction and classification workflows. The task allows you to calculate and compile information from many different data sources into a single, spatially continuous layer in one step. This layer can then be used with the EnrichFromMultiVariableGrid operation to quickly enrich point features with the variables you have calculated, reducing the amount of effort required to build prediction and classification models from point data.
Request parameters
Parameter | Details |
---|---|
| The type of bin that will be used to generate the result grid. The default is Analysis using Values: REST examples
|
| The distance for the bins of type REST examples
|
| The distance unit for the bins will be used to calculate Values: REST examples
|
| A list of input layers that will be used in analysis. Each input layer follows the same formatting as described in the Feature Input topic. This can be one of the following:
In the REST web example for REST web example
|
| A JSON array containing objects that describe the variables that will be calculated for each layer in |
|
The task will create a feature service of the results. You define the name of the service. REST examples
|
|
The
Syntax:
|
|
The response format. The default response format is Values: |
variableCalculations syntax and examples
The following sections outline how to populate the variable
parameter.
variableCalculations syntax
In the syntax example below, "layer" is the index of the layer in input
that will be used to calculate the specified variables; variables are an array of JSON objects that describe the variables you want to include in the result layer and must contain at least one variable for each layer; and type can be one of the following variable types:
Distance
To Nearest Attribute
Of Nearest Attribute
Summary Of Related
Each type must be configured with a unique set of parameters, defined in the table below:
Parameter | Details |
---|---|
| The name of the field that will be created in the result layer to store a variable. |
| Defines the maximum distance that the tool will search from the center of each bin to find a feature in the layer for |
| Defines the maximum distance unit that the tool will search from the center of each bin to find a feature in the layer for |
| 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. Required by |
| The name of a field in the input layer. The field's values will be used to calculate |
| Required by
|
| Optional for all variable types. This is formatted as described in the Feature Input topic. |
Syntax example
[
{
"layer":<index>,
"variables":[
{
"type":"DistanceToNearest",
"outFieldName":"<output field name>",
"searchDistance":<number>,
"searchDistanceUnit":"<unit>",
"filter":"<filter>"
},
{
"type":"AttributeOfNearest",
"outFieldName":"<output field name>",
"attributeField":"<field name>",
"searchDistance":<number>,
"searchDistanceUnit":"<unit>",
"filter":"<filter>"
},
{
"type":"AttributeSummaryOfRelated",
"outFieldName":"<output field name>",
"statisticType":"<statistic type>",
"statisticField":"<field name>",
"searchDistance":<number>,
"searchDistanceUnit":"<unit>",
"filter":"<filter>"
},
...
]
},
...
]
variableCalculations examples
In the REST web example for variable
below, two variables are calculated for the layer at index 0 of the input
list. distance
is the distance from each bin center to the nearest feature where the type
is specified as hurricane
, and rating
is the value of field storm
in the nearest feature to each bin center. A variable named mean
is calculated for the layer at index 1 of the input
list; it is the mean value of field wind
in all features within a 20-mile radius of each bin center. All three variables are stored in the attribute table of the output layer.
REST web example for variable
[
{
"layer":0,
"variables":[
{
"type":"DistanceToNearest",
"outFieldName":"distance_to_nearest_hurricane",
"searchDistance":100,
"searchDistanceUnit":"Miles",
"filter":"type = 'hurricane'"
},
{
"type":"AttributeOfNearest",
"outFieldName":"rating_of_nearest_hurricane",
"attributeField":"storm_rating",
"searchDistance":100,
"searchDistanceUnit":"Miles"
}
]
},
{
"layer":1,
"variables":[
{
"type":"AttributeSummaryOfRelated",
"outFieldName":"mean_wind_speed",
"statisticType":"mean",
"statisticField":"wind_speed",
"searchDistance":20,
"searchDistanceUnit":"Miles"
}
]
}
]
In the REST scripting example for variable
below, two variables are calculated for the layer at index 0 of the input
list. The variable distance
is the distance from each bin center to the nearest feature where the type
is specified as hurricane
, and distance
is the equivalent variable where the type
is tropical storm
. Both are stored in the attribute table of the output layer.
REST scripting example for variable
"variableCalculations":[
{
"layer":0,
"variables":[
{
"type":"DistanceToNearest",
"outFieldName":"distance_to_nearest_hurricane",
"searchDistance":100,
"searchDistanceUnit":"Miles",
"filter":"type = 'hurricane'"
},
{
"type":"DistanceToNearest",
"outFieldName":"distance_to_nearest_trop_storm",
"searchDistance":100,
"searchDistanceUnit":"Miles",
"filter":"type = 'tropical storm'"
}
]
}
]
Example usage
Below is a sample request URL for Build
:
https://hostname.domain.com/webadaptor/rest/services/System/GeoAnalyticsTools/GPServer/BuildMultiVariableGrid/submitJob?inputLayer={"url":"https://hostname.domain.com/webadaptor/rest/services/Hurricane/hurricaneTrack/0"}&bintype=Hexagon&binSize=108.3&binSizeUnit=Meters&variableCalculations=[{"layer":0,"variables":[{"type":"DistanceToNearest","outFieldName":"distance_to_nearest_hurricane","searchDistance":100,"searchDistanceUnit":"Miles","filter":"type = "hurricane""},{"type":"DistanceToNearest","outFieldName":"distance_to_nearest_trop_storm","searchDistance":100,"searchDistanceUnit":"Miles","filter":"type = "tropical storm""}]}]&outputName=myOutput&context={"extent":{"xmin":-122.68,"ymin":45.53,"xmax":-122.45,"ymax":45.6,"spatialReference":{"wkid":4326}}}&f=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 job
to periodically check the status of the job and messages as described in Check job status. Once the job has successfully completed, use job
to retrieve the results. To track the status, you can make a request of the following form:
https://<analysis url>/BuildMultiVariableGrid/jobs/<jobId>
Access results
When the status of the job request is esri
, you can access the results of the analysis by making a request of the following form:
https://<analysis-url>/BuildMultiVariableGrid/jobs/<jobId>/results/output?token=<your token>&f=json
Response | Description |
---|---|
| The result output will always contain polygon features. The number of resulting polygons is based on
The result has properties for parameter name, data type, and value. The contents of
See Feature output for more information about how the result layer is accessed. |