Build Multi-Variable Grid—ArcGIS REST APIs

URL:https://<geoanalytics-url>/BuildMultiVariableGrid
Version Introduced:10.6.1

Description

The BuildMultiVariableGrid 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:

DistanceToNearest—The distance from each bin to the nearest feature.
AttributeOfNearest—An attribute value of the feature nearest to each bin.
AttributeSummaryOfRelated—A statistical summary of all features within searchDistance of each bin.

Only variables you specify in variableCalculations 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 BuildMultiVariableGrid 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
binType (Required)	The type of bin that will be used to generate the result grid. Analysis using Square or Hexagon bins requires a projected coordinate system. When aggregating layers into bins, the input layer or processing extent (processSR) must have a projected coordinate system. At 10.5.1, 10.6, and 10.6.1, if a projected coordinate system is not specified when running analysis, the World Cylindrical Equal Area (WKID 54034) projection will be used. At 10.7 or later, if a projected coordinate system is not specified when running analysis, a projection will be picked based on the extent of the data. Values: Hexagon \| Square (default) REST examples `//REST web example Hexagon //REST scripting example "binType": "Hexagon"`
binSize (Required)	The distance for the bins of type binType in the output polygon layer. variableCalculations will be calculated at the center of each bin. When generating Square bins, the number and units specified determine the height and length of the square. For Hexagon bins, the number and units specified determine the distance between parallel sides. REST examples `//REST web example 108.3 //REST scripting example "binSize": 100`
binSizeUnit (Required)	The distance unit for the bins will be used to calculate variableCalculations. Values: Meters \| Kilometers \| Feet \| FeetInt \| FeetUS \| Miles \| MilesInt \| MilesUS \| NauticalMiles \| NauticalMilesInt \| NauticalMilesUS \| Yards \| YardsInt \| YardsUS REST examples `//REST web example Meters //REST scripting example "binSizeUnit": "Miles"`
inputLayers (Required)	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: 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 In the REST web example for inputLayers below, two layers are being used in analysis. The layer at index 0 will be filtered to only use features where OID > 2. REST web example `[ { "url":"https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter":"OID > 2" }, { "url":"https://myportal.domain.com/server/rest/services/Hosted/weatherPoints/FeatureServer/0" } ]`
variableCalculations (Required)	A JSON array containing objects that describe the variables that will be calculated for each layer in inputLayers.
outputName (Required)	The task will create a feature service of the results. You define the name of the service. REST examples `//REST web example myOutput //REST scripting example "outputName": "myOutput"`
context (Optional)	The context parameter 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

variableCalculations syntax and examples

The following sections outline how to populate the variableCalculations parameter and examples.

variableCalculations syntax

In the syntax example below, layer is the index of the layer in inputLayers 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:

DistanceToNearest
AttributeOfNearest
AttributeSummaryOfRelated

Each type must be configured with a unique set of parameters, defined in the table below:


Parameter	Details
outFieldName	The name of the field that will be created in the result layer to store a variable.
searchDistance	Defines the maximum distance that the tool will search from the center of each bin to find a feature in the layer for DistanceToNearest and AttributeOfNearest. If no feature is within the distance, null is returned. For AttributeOfSummaryRelated, searchDistance is optional and defines the radius of a circular neighborhood surrounding each bin. All features that intersect this neighborhood will be used to calculate statisticType. If a distance is not defined, only features that intersect a bin will be used to calculate statisticType.
searchDistanceUnit	Defines the maximum distance unit that the tool will search from the center of each bin to find a feature in the layer for DistanceToNearest and AttributeOfNearest. If no feature is within the distance, null is returned. For AttributeOfSummaryRelated, searchDistance is optional and defines the radius of a circular neighborhood surrounding each bin. All features that intersect this neighborhood will be used to calculate statisticType. If a distance is not defined, only features that intersect a bin will be used to calculate statisticType.
attributeField	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 AttributeOfNearest.
statisticField	The name of a field in the input layer. The field's values will be used to calculate statisticType. Required by AttributeSummaryOfRelated.
statisticType	Required by AttributeSummaryOfRelated. Can be defined as one of the following types: Count—For a numeric field, this totals the number of features near or intersecting each bin. For a string field, this totals the number of strings for all features near or intersecting each bin. Sum—Adds the total value of all features near or intersecting each bin. This is used for numeric fields. Mean—Calculates the average of all features near or intersecting each bin. This is used for numeric fields. Min—Finds the smallest value of all features near or intersecting each bin. This is used for numeric fields. Max—Finds the largest value of all features near or intersecting each bin. This is used for numeric fields. Range—Finds the difference between Min and Max. This is used for numeric fields. Stddev—Finds the standard deviation of all features near or intersecting each bin. This is used for numeric fields. Var—Finds the variance of all features near or intersecting each bin. This is used for numeric fields. Any—Returns a sample string of all features near or intersecting each bin. This is used for string fields.
filter	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 variableCalculations below, two variables are calculated for the layer at index 0 of the inputLayers list. 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. A variable named mean_wind_speed is calculated for the layer at index 1 of the inputLayers list; it is the mean value of field wind_speed 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 variableCalculations

[
    {
        "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 variableCalculations below, two variables are calculated for the layer at index 0 of the inputLayers list. The variable 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 the equivalent variable where type = "tropical storm". Both are stored in the attribute table of the output layer.

REST scripting example for variableCalculations

"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 BuildMultiVariableGrid:

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 jobId to periodically check the status of the job and messages as described in Check job status. Once the job has successfully completed, use jobId 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 esriJobSucceeded, 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
output	The result output will always contain polygon features. The number of resulting polygons is based on binSize, variableCalculations, and the extent of the input data. The layer will only contain the variables specified in variableCalculations. `{"url": "https://<analysis-url>/BuildMultiVariableGrid/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.

ArcGIS REST APIs