ArcGIS REST API

Build Multi-Variable Grid

Build Multi-Variable Grid

The Build Multi-Variable Grid task 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 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 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 U.S.?
  • Given a layer of household income, where in the U.S. is the variation of income in the surrounding 50 miles the greatest?

The result of Build Multi-Variable Grid 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, reducing the amount of effort required to build prediction and classification models.

Note:

Build Multi -Variable Grid is available at ArcGIS Enterprise 10.6.1.

Request URL

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

Request parameters

ParameterDescription

binType

(Required)

The type of bin that will be used to generate the result grid. Bin options are the following:

  • Hexagon
  • Square—This is the default.

REST web example: Hexagon

REST scripting example: "binType" : "Hexagon"

Note:

Analysis using Square or Hexagon bins requires a projected coordinate system. When aggregating layers into bins, the input layers or processing extent (processSR) must have a projected coordinate system. If a projected coordinate system is not specified when running analysis, the World Cylindrical Equal Area (WKID 54034) projection will be used.

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 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 variableCalculations.

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

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 shown 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 for inputLayers

[
   {
      "url":"http://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0",
      "filter":"OID > 2"
   },
   {
      "url":"http://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.

Syntax:

variableCalculations syntax

[
    {
        "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>"
            },
            ...
        ]
    },
    ...
]

layer is the index of the layer in inputLayers that will be used to calculate the specified variables.

variables is an array of JSON objects that describe the variables you want to include in the result layer. The array must contain at least one variable for each layer.

type can be one of the following variable 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 a variable. This is required.
  • searchDistance and searchDistanceUnit are a number and linear unit. For DistanceToNearest and AttributeOfNearest, searchDistance and searchDistanceUnit are required and define 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 and searchDistanceUnit are optional and define 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 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 variable types and is formatted as described in the Feature Input topic.

In the REST web example for variableCalculations shown 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 called 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 shown 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""  
            }
        ]
    }
]"

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

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

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 jobId to retrieve the results. To track the status, you can make a request of the following form:

http://<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:

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

ParameterDescription

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.

Request example:
{"url": 
"http://<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.