Locate Regions

URL:: https://<root>/<serviceName>/RasterAnalysisTools/GPServer/LocateRegions
Methods:: GET
Version Introduced:: 10.9.1

Description

The LocateRegions task identifies the best regions, or groups of contiguous cells, from an input utility (suitability) raster that satisfy a specified evaluation criterion and that meet identified shape, size, number, and interregion distance constraints.

Some example applications of LocateRegions include the following:

Find the most preferred deer habitat to conserve. Eight habitat patches (regions) are needed to maintain a viable population and each region must be approximately 50 contiguous acres. To support breeding opportunities within the herd, the regions should be close enough to one another so that they can be feasibly connected via wildlife corridors.
Find the best locations to extract timber for a logging operation. To be financially viable, the areas (regions) to be logged must be at least 250 contiguous acres and each region must be within one mile from another.
Find the ideal location for a new shopping center. The shopping center requires the best 60 acres, however, for construction purposes, the area need to be contiguous and the shape of the building site (region) should be as compact as possible.

Request parameters

Parameter Details

Parameter	Details
`inputRaster` (Required)	The input utility raster from which the regions will be derived. The higher the value in the input raster, the greater the utility. The input raster can be either an integer or a floating-point type. Raster input examples: Use dark colors for code blocksCopy `1 2 3 4 5 //Portal item as input raster "inputRaster":{"itemId": <portal item Id>} //URL as input raster "inputRaster":{"url": <image service layer url>}`
`outputName` (Required)	The name of the output image service that will be created. You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter. Syntax: A JSON object describes the name of the output or the output raster. Output name example: Use dark colors for code blocksCopy `1 "outputName":{"serviceProperties":{"name":"testrasteranalysis"}}` Output raster examples: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 //Output portal item: "outputName":{"itemId": <portal item id>} //Output url: "outputName":{"url": <image service url} //Output raster layer service: "outputName":{"serviceProperties": {"name":"testrasteranalysis", "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"} }`
`totalArea`	The total amount of area for all regions. The default is 10 percent of the input cells within the processing extent. Example: Use dark colors for code blocksCopy `1 "totalArea": 17.5`
`areaUnits`	Defines the area units used for the Total area, Region minimum area, and Region maximum area parameters. Syntax: The input can be one of the following: `SQUARE_MAP_UNITS` — For the square of the linear units of the output spatial reference. This is the default. `SQUARE_MILES` — For miles `SQUARE_KILOMETERS` — For kilometers `HECTARES` — For hectares `ACRES` — For acres `SQUARE_METERS` — For meters `SQUARE_YARDS` — For yards `SQUARE_FEET` — For feet Example: Use dark colors for code blocksCopy `1 "areaUnits": "ACRES"`
`numberOfRegions`	Determines how many regions the `totalArea` will be distributed across. The maximum number of regions that can be specified is 30. The default is 1. Example: Use dark colors for code blocksCopy `1 "numberOfRegions": 5`
`regionShape`	Defines the shape characteristics for the output regions. Syntax: The input can be one of the following: `CIRCLE` — Cells that maintain circular regions will receive a greater weight. This is the default. `ELLIPSE` — Cells that maintain elliptical-shaped regions will receive a greater weight. `EQUILATERAL_TRIANGLE` — Cells that maintain equilateral triangular-shaped regions will receive a greater weight. `SQUARE` — Cells that maintain square-shaped regions will receive a greater weight. `PENTAGON` — Cells that maintain pentagon-shaped regions will receive a greater weight. `HEXAGON` — Cells that maintain hexagon-shaped regions will receive a greater weight. `OCTAGON` — Cells that maintain octagon-shaped regions will receive a greater weight. Example: Use dark colors for code blocksCopy `1 "regionShape": "OCTAGON"`
`regionOrientation`	Defines the orientation of the defined shape. Regions are grown out from the seed locations with preference given to the cells that maintain the desired orientation of the region shapes. The orientation values are in compass degrees ranging from 0 to 360, increasing clockwise starting from north. The default is 0. The default of 0 orients the shapes in the following manner: Circle-no effect; Ellipse-the minor axis is orientated north-south; Triangle and Pentagon-one point is straight up; Square, Hexagon, and Octagon-one flat side is oriented east-west. If the `regionShape` is set to Circle, this parameter is unavailable. Example: Use dark colors for code blocksCopy `1 "regionOrientation": 15`
`shapeTradeoff`	Identifies the weight for the cells when growing the candidate regions in the parameterized region-growing algorithm. The weighting is a tradeoff between a cell's contribution for maintaining the region shape relative to the utility contribution of the cell's attribute value. Higher values indicates maintaining the shape of the region is more important than selecting higher utility values. The acceptable percent values are 0 to 100, inclusively. The default is 50. This parameter is used to identify the feasible candidate regions. The candidate regions that will be selected by the algorithm are controlled by the `evaluationMethod` parameter. Example: Use dark colors for code blocksCopy `1 "shapeTradeoff": 95`
`evaluationMethod`	The evaluation criteria to be used for determining which of the candidate regions identified in the parameterized region-growing algorithm are most preferred. The preference can be specified based on a particular statistic of the utility values, or spatial arrangement of the cells within the regions. Syntax: The input can be one of the following: `HIGHEST_AVERAGE_VALUE` — Selects regions based on the highest average value. This is the default. `HIGHEST_SUM` — Selects regions based on the highest sum. `HIGHEST_MEDIAN_VALUE` — Selects regions based on the highest median value. `HIGHEST_VALUE` — Selects regions based on the highest individual cell value contained within the region. This option ensures the best individual cells are selected. `LOWEST_VALUE` — Selects regions based on the highest lowest individual cell value contained within the region. This option ensures the selected regions contain cells with really low utility. `GREATEST_CORE_AREA` — Selects regions based on the greatest core area. Any cell that is farther than one cell from the edge of a region is considered to be part of the core. The edge distance can be controlled by the analysis cell size. Setting a smaller cell size can increase the core area. `HIGHEST_SUM_OF_CORE_UTILITY_VALUES` — Selects regions based on the highest cumulative sum of the utility values for the core area. The edge distance can be controlled by the analysis cell size. `GREATEST_EDGE` — Selects regions based on the greatest amount of edge using the P1 ratio, which is the ratio of the perimeter of the shape to the perimeter of a circle of the same area. The P1 ratio for a circle is 1. Example: Use dark colors for code blocksCopy `1 "evaluationMethod": "HIGHEST_VALUE"`
`minimumArea`	Define the minimum area allowed for each region. The units specified by the `areaUnits` parameter will be used. Example: Use dark colors for code blocksCopy `1 "minimumArea": 2`
`maximumArea`	Define the maximum area allowed for each region. The units specified by the `areaUnits` parameter will be used. Example: Use dark colors for code blocksCopy `1 "maximumArea": 5`
`minimumDistance`	Define the minimum distance allowed between regions. No two regions can be within this distance. This parameter influences the parameterized region-growing (PRG) algorithm. If a cell has the potential of being added to a candidate region, but it is within this distance from any individual region in the dataset specified by the `inExistingRegions` parameter, in that at least one of the selected regions must be within the maximum distance from existing regions. The maximum distance setting is not applied to excluded areas (NoData cells) and has no effect on the PRG algorithm. The units specified by the `distanceUnits` parameter will be used. Example: Use dark colors for code blocksCopy `1 "minimumDistance": 1`
`maximumDistance`	Define the maximum distance allowed between regions. No region can be farther apart than this distance from at least one other region. When sequentially selecting regions, if the next best region is farther than this distance from any of the already selected regions, it will not be considered at this time, but it may be selected later when more regions are selected. The maximum distance is applied to the dataset specified in the `inExistingRegions` parameter, in that at least one of the selected regions must be within the maximum distance from existing regions. The maximum distance setting is not applied to excluded areas (NoData cells) and has no effect on the PRG algorithm. The units specified by the `distanceUnits` parameter will be used. Example: Use dark colors for code blocksCopy `1 "maximumDistance": 3`
`distanceUnits`	Defines the distance units that will be used for the Minimum distance between regions and Maximum distance between regions parameters. Syntax: The input can be one of the following: `MAP_UNITS` — For the s linear units of the output spatial reference. This is the default. `MILES` — For miles `KILOMETERS` — For kilometers `METERS` — For meters `YARDS` — For yards `FEET` — For feet Example: Use dark colors for code blocksCopy `1 "distanceUnits": "YARDS"`
`inExistingRegions`	A dataset identifying where regions already exist. The input can be a raster or feature dataset. If the input is a raster, any location in the raster with a valid value is considered already allocated. All other locations are set to NoData. In the parameterized region-growing algorithm, no region will grow from any location identified as an existing region. Existing regions will be used in the growth and evaluation of the `minimumDistance` and `maximumDistance` parameters as described in the corresponding parameter descriptions above. Input raster of existing regions example: Use dark colors for code blocksCopy `1 2 3 4 5 //Portal item as input raster "inExistingRegions":{"itemId": <portal item Id>} //URL as input raster "inExistingRegions":{"url": <image service layer url>}` Input feature of existing regions example: Use dark colors for code blocksCopy `1 2 3 4 5 //Feature layer URL "inExistingRegions":{"url": <feature service layer url>} //Feature collection "inExistingRegions":{"layerDefinition": {}, "featureSet": {}}`
`numberOfNeighbors`	Defines which neighboring cells to use in the growth of the regions. Syntax: A String field that can be "FOUR" or "EIGHT": `FOUR` — Only the four direct (orthogonal) neighbors of the region cells will be considered in the region growth. `EIGHT` — The eight nearest neighbors (orthogonal and diagonal) will be considered in the region growth. This is the default. Example: Use dark colors for code blocksCopy `1 "numberOfNeighbors": "EIGHT"`
`noIslands`	Defines whether or not islands will be allowed within the potential regions. Syntax: A Boolean value as either `true` or `false` . A value of `true` specifies that there will be no islands within a region. A flood field algorithm is implemented as a postprocess once the regions are created but before the regions are selected. If there are islands within a region, they will be filled in and the cells will join the region. Since the fill process occurs before the selection process, the utility of the island cells will be added to the region, and their values will be included in the selection process of the regions and in the statistics of the output regions. As a result of the fill process, it is likely that the total area allocated will exceed the target specified by the `totalArea` parameter. A value of `false` specifies that there will be islands within a region. Example: Use dark colors for code blocksCopy `1 "noIslands": true`
`regionSeeds`	Defines the number of seeds from which to grow the potential regions. Syntax: The input can be one of the following: `BASED_ON_INPUT` —The number of seeds will be based on the number of cells in the input raster. When the input raster has 100,000 cells or fewer, the default is Maximum. When the input raster has more than 100,000 cells, the default is Small. This is the default. `SMALL` —The number of seeds will be equal to 10 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 1,600 seeds. `MEDIUM` —The number of seeds will be equal to 20 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 2,500 seeds. `LARGE` — The number of seeds will be equal to 30 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 3,600 seeds. `MAXIMUM` —The region growth will occur at each available cell within the input raster. Available cells are all cells that are not NoData and not identified as an existing region. Example: Use dark colors for code blocksCopy `1 "regionSeeds": "MEDIUM"`
`regionResolution`	Sets the resolution at which region growth occurs. Syntax: The input can be one of the following: `BASED_ON_INPUT` —The resolution will be based on the number of cells in the input raster. When the input raster has 500,000 cells or fewer, the default is Maximum. When the input raster has more than 500,000 cells, the default is Low. This is the default. `LOW` —The analysis will be performed on an intermediate raster containing 147,356 (384 x 384) cells distributed in the same x and y ratio as the input raster. `MEDIUM` —The analysis will be performed on an intermediate raster containing 262,144 (512 x 512) cells distributed in the same x and y ratio as the input raster. `HIGH` —The analysis will be performed on an intermediate raster containing 589,824 (768 x 768) cells distributed in the same x and y ratio as the input raster. `MAXIMUM` —The analysis will be performed on all cells in the input raster. Example: Use dark colors for code blocksCopy `1 "regionResolution": "LOW"`
`selectionMethod`	Identifies how the regions will be selected. Syntax: The input can be one of the following: `BASED_ON_NUMBER_OF_REGIONS` —The selection method is based on the Number of regions parameter. If the Number of regions is eight or less, the Combinatorial selection method is used. If the Number of regions parameter is greater than eight, the Sequential selection method is used. This is the default. `COMBINATORIAL` —Selects the best regions based on the specified evaluation method, while honoring the spatial constraints, by testing all combinations of the desired number of regions within the candidate regions from the parameterized region-growing (PRG) algorithm. `SEQUENTIAL` — Sequentially selects the best regions based on the evaluation method and that meets the spatial constraints until the desired number of regions is reached. Example: Use dark colors for code blocksCopy `1 "selectionMethod": "SEQUENTIAL"`
`context`	Contains additional settings that affect task processing. This task has the following settings: Extent (`extent` )—A bounding box that defines the analysis area. Output Spatial Reference (`outSR` )—The output raster will be projected into the output spatial reference. Snap Raster (`snapRaster` )—The output raster will have its cells aligned with the specified snap raster. Cell Size (`cellSize` )—The output raster will have the resolution specified by cell size. Mask (`mask`)—Only cells that fall within the analysis mask will be considered in the operation.
`f`	The response format. The default response format is `html` . Values: `html \| json \| pjson`

inputRaster

(Required)

The input utility raster from which the regions will be derived. The higher the value in the input raster, the greater the utility.

The input raster can be either an integer or a floating-point type.

Raster input examples:

Use dark colors for code blocksCopy
//Portal item as input raster
"inputRaster":{"itemId": <portal item Id>}

//URL as input raster
"inputRaster":{"url": <image service layer url>}

outputName

(Required)

The name of the output image service that will be created.

You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter.

Syntax: A JSON object describes the name of the output or the output raster.

Output name example:

Use dark colors for code blocksCopy
"outputName":{"serviceProperties":{"name":"testrasteranalysis"}}

Output raster examples:

Use dark colors for code blocksCopy
//Output portal item:
"outputName":{"itemId": <portal item id>}

//Output url:
"outputName":{"url": <image service url}

//Output raster layer service:
"outputName":{"serviceProperties":
  {"name":"testrasteranalysis",
    "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"},
  "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"}
}

totalArea

The total amount of area for all regions.

The default is 10 percent of the input cells within the processing extent.

Example:

Use dark colors for code blocksCopy
"totalArea": 17.5

areaUnits

Defines the area units used for the Total area, Region minimum area, and Region maximum area parameters.

Syntax: The input can be one of the following:

SQUARE_MAP_UNITS — For the square of the linear units of the output spatial reference. This is the default.
SQUARE_MILES — For miles
SQUARE_KILOMETERS — For kilometers
HECTARES — For hectares
ACRES — For acres
SQUARE_METERS — For meters
SQUARE_YARDS — For yards
SQUARE_FEET — For feet

Example:

Use dark colors for code blocksCopy
"areaUnits": "ACRES"

numberOfRegions

Determines how many regions the totalArea will be distributed across.

The maximum number of regions that can be specified is 30. The default is 1.

Example:

Use dark colors for code blocksCopy
"numberOfRegions": 5

regionShape

Defines the shape characteristics for the output regions.

Syntax: The input can be one of the following:

CIRCLE — Cells that maintain circular regions will receive a greater weight. This is the default.
ELLIPSE — Cells that maintain elliptical-shaped regions will receive a greater weight.
EQUILATERAL_TRIANGLE — Cells that maintain equilateral triangular-shaped regions will receive a greater weight.
SQUARE — Cells that maintain square-shaped regions will receive a greater weight.
PENTAGON — Cells that maintain pentagon-shaped regions will receive a greater weight.
HEXAGON — Cells that maintain hexagon-shaped regions will receive a greater weight.
OCTAGON — Cells that maintain octagon-shaped regions will receive a greater weight.

Example:

Use dark colors for code blocksCopy
"regionShape": "OCTAGON"

regionOrientation

Defines the orientation of the defined shape. Regions are grown out from the seed locations with preference given to the cells that maintain the desired orientation of the region shapes.

The orientation values are in compass degrees ranging from 0 to 360, increasing clockwise starting from north. The default is 0.

The default of 0 orients the shapes in the following manner: Circle-no effect; Ellipse-the minor axis is orientated north-south; Triangle and Pentagon-one point is straight up; Square, Hexagon, and Octagon-one flat side is oriented east-west.

If the regionShape is set to Circle, this parameter is unavailable.

Example:

Use dark colors for code blocksCopy
"regionOrientation": 15

shapeTradeoff

Identifies the weight for the cells when growing the candidate regions in the parameterized region-growing algorithm. The weighting is a tradeoff between a cell's contribution for maintaining the region shape relative to the utility contribution of the cell's attribute value.

Higher values indicates maintaining the shape of the region is more important than selecting higher utility values. The acceptable percent values are 0 to 100, inclusively. The default is 50.

This parameter is used to identify the feasible candidate regions. The candidate regions that will be selected by the algorithm are controlled by the evaluationMethod parameter.

Example:

Use dark colors for code blocksCopy
"shapeTradeoff": 95

evaluationMethod

The evaluation criteria to be used for determining which of the candidate regions identified in the parameterized region-growing algorithm are most preferred. The preference can be specified based on a particular statistic of the utility values, or spatial arrangement of the cells within the regions.

Syntax: The input can be one of the following:

HIGHEST_AVERAGE_VALUE — Selects regions based on the highest average value. This is the default.
HIGHEST_SUM — Selects regions based on the highest sum.
HIGHEST_MEDIAN_VALUE — Selects regions based on the highest median value.
HIGHEST_VALUE — Selects regions based on the highest individual cell value contained within the region. This option ensures the best individual cells are selected.
LOWEST_VALUE — Selects regions based on the highest lowest individual cell value contained within the region. This option ensures the selected regions contain cells with really low utility.
GREATEST_CORE_AREA — Selects regions based on the greatest core area. Any cell that is farther than one cell from the edge of a region is considered to be part of the core. The edge distance can be controlled by the analysis cell size. Setting a smaller cell size can increase the core area.
HIGHEST_SUM_OF_CORE_UTILITY_VALUES — Selects regions based on the highest cumulative sum of the utility values for the core area. The edge distance can be controlled by the analysis cell size.
GREATEST_EDGE — Selects regions based on the greatest amount of edge using the P1 ratio, which is the ratio of the perimeter of the shape to the perimeter of a circle of the same area. The P1 ratio for a circle is 1.

Example:

Use dark colors for code blocksCopy
"evaluationMethod": "HIGHEST_VALUE"

minimumArea

Define the minimum area allowed for each region.

The units specified by the areaUnits parameter will be used.

Example:

Use dark colors for code blocksCopy
"minimumArea": 2

maximumArea

Define the maximum area allowed for each region.

The units specified by the areaUnits parameter will be used.

Example:

Use dark colors for code blocksCopy
"maximumArea": 5

minimumDistance

Define the minimum distance allowed between regions. No two regions can be within this distance.

This parameter influences the parameterized region-growing (PRG) algorithm. If a cell has the potential of being added to a candidate region, but it is within this distance from any individual region in the dataset specified by the inExistingRegions parameter, in that at least one of the selected regions must be within the maximum distance from existing regions. The maximum distance setting is not applied to excluded areas (NoData cells) and has no effect on the PRG algorithm.

The units specified by the distanceUnits parameter will be used.

Example:

Use dark colors for code blocksCopy
"minimumDistance": 1

maximumDistance

Define the maximum distance allowed between regions. No region can be farther apart than this distance from at least one other region.

When sequentially selecting regions, if the next best region is farther than this distance from any of the already selected regions, it will not be considered at this time, but it may be selected later when more regions are selected.

The maximum distance is applied to the dataset specified in the inExistingRegions parameter, in that at least one of the selected regions must be within the maximum distance from existing regions. The maximum distance setting is not applied to excluded areas (NoData cells) and has no effect on the PRG algorithm.

The units specified by the distanceUnits parameter will be used.

Example:

Use dark colors for code blocksCopy
"maximumDistance": 3

distanceUnits

Defines the distance units that will be used for the Minimum distance between regions and Maximum distance between regions parameters.

Syntax: The input can be one of the following:

MAP_UNITS — For the s linear units of the output spatial reference. This is the default.
MILES — For miles
KILOMETERS — For kilometers
METERS — For meters
YARDS — For yards
FEET — For feet

Example:

Use dark colors for code blocksCopy
"distanceUnits": "YARDS"

inExistingRegions

A dataset identifying where regions already exist.

The input can be a raster or feature dataset. If the input is a raster, any location in the raster with a valid value is considered already allocated. All other locations are set to NoData.

In the parameterized region-growing algorithm, no region will grow from any location identified as an existing region. Existing regions will be used in the growth and evaluation of the minimumDistance and maximumDistance parameters as described in the corresponding parameter descriptions above.

Input raster of existing regions example:

Use dark colors for code blocksCopy
//Portal item as input raster
"inExistingRegions":{"itemId": <portal item Id>}

//URL as input raster
"inExistingRegions":{"url": <image service layer url>}

Input feature of existing regions example:

Use dark colors for code blocksCopy
//Feature layer URL
"inExistingRegions":{"url": <feature service layer url>}

//Feature collection
"inExistingRegions":{"layerDefinition": {}, "featureSet": {}}

numberOfNeighbors

Defines which neighboring cells to use in the growth of the regions.

Syntax: A String field that can be "FOUR" or "EIGHT":

FOUR — Only the four direct (orthogonal) neighbors of the region cells will be considered in the region growth.
EIGHT — The eight nearest neighbors (orthogonal and diagonal) will be considered in the region growth. This is the default. Example:

Use dark colors for code blocksCopy
"numberOfNeighbors": "EIGHT"

noIslands

Defines whether or not islands will be allowed within the potential regions.

Syntax: A Boolean value as either true or false .

A value of true specifies that there will be no islands within a region. A flood field algorithm is implemented as a postprocess once the regions are created but before the regions are selected. If there are islands within a region, they will be filled in and the cells will join the region. Since the fill process occurs before the selection process, the utility of the island cells will be added to the region, and their values will be included in the selection process of the regions and in the statistics of the output regions. As a result of the fill process, it is likely that the total area allocated will exceed the target specified by the totalArea parameter.
A value of false specifies that there will be islands within a region.

Example:

Use dark colors for code blocksCopy
"noIslands": true

regionSeeds

Defines the number of seeds from which to grow the potential regions.

Syntax: The input can be one of the following:

BASED_ON_INPUT —The number of seeds will be based on the number of cells in the input raster. When the input raster has 100,000 cells or fewer, the default is Maximum. When the input raster has more than 100,000 cells, the default is Small. This is the default.
SMALL —The number of seeds will be equal to 10 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 1,600 seeds.
MEDIUM —The number of seeds will be equal to 20 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 2,500 seeds.
LARGE — The number of seeds will be equal to 30 percent of the number of cells in the input raster, after NoData cells are excluded, but not to exceed 3,600 seeds.
MAXIMUM —The region growth will occur at each available cell within the input raster. Available cells are all cells that are not NoData and not identified as an existing region.

Example:

Use dark colors for code blocksCopy
"regionSeeds": "MEDIUM"

regionResolution

Sets the resolution at which region growth occurs.

Syntax: The input can be one of the following:

BASED_ON_INPUT —The resolution will be based on the number of cells in the input raster. When the input raster has 500,000 cells or fewer, the default is Maximum. When the input raster has more than 500,000 cells, the default is Low. This is the default.
LOW —The analysis will be performed on an intermediate raster containing 147,356 (384 x 384) cells distributed in the same x and y ratio as the input raster.
MEDIUM —The analysis will be performed on an intermediate raster containing 262,144 (512 x 512) cells distributed in the same x and y ratio as the input raster.
HIGH —The analysis will be performed on an intermediate raster containing 589,824 (768 x 768) cells distributed in the same x and y ratio as the input raster.
MAXIMUM —The analysis will be performed on all cells in the input raster.

Example:

Use dark colors for code blocksCopy
"regionResolution": "LOW"

selectionMethod

Identifies how the regions will be selected.

Syntax: The input can be one of the following:

BASED_ON_NUMBER_OF_REGIONS —The selection method is based on the Number of regions parameter. If the Number of regions is eight or less, the Combinatorial selection method is used. If the Number of regions parameter is greater than eight, the Sequential selection method is used. This is the default.
COMBINATORIAL —Selects the best regions based on the specified evaluation method, while honoring the spatial constraints, by testing all combinations of the desired number of regions within the candidate regions from the parameterized region-growing (PRG) algorithm.
SEQUENTIAL — Sequentially selects the best regions based on the evaluation method and that meets the spatial constraints until the desired number of regions is reached.

Example:

Use dark colors for code blocksCopy
"selectionMethod": "SEQUENTIAL"

context

Contains additional settings that affect task processing. This task has the following settings:

Extent (extent )—A bounding box that defines the analysis area.
Output Spatial Reference (outSR )—The output raster will be projected into the output spatial reference.
Snap Raster (snapRaster )—The output raster will have its cells aligned with the specified snap raster.
Cell Size (cellSize )—The output raster will have the resolution specified by cell size.
Mask (mask)—Only cells that fall within the analysis mask will be considered in the operation.

f

The response format. The default response format is html .

Values: html | json | pjson

Response

When you submit a request, the task assigns a unique job ID for the transaction.

Use dark colors for code blocksCopy
{
  "jobId": "<unique job identifier>",
  "jobStatus": "<job status>"
}

After the initial request is submitted, you can use the jobId to periodically check the status of the job and messages as described in Checking job status. Once the job has successfully completed, you use the jobId to retrieve the results. To track the status, you can make a request of the following form:

Use dark colors for code blocksCopy
https://<raster analysis tools url>/LocateRegions/jobs/<jobId>

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:

Use dark colors for code blocksCopy
https://<raster analysis tools url>/LocateRegions/jobs/<jobId>/results/outputRaster

Example usage

Below is a sample request URL for LocateRegions .

Use dark colors for code blocksCopy
https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/LocateRegions/submitJob

JSON Response syntax

The response returns the outputRaster output parameter, which has properties for parameter name, data type, and value. The content of value is always the output raster dataset itemId and the image service URL.

Use dark colors for code blocksCopy
{
  "paramName": <parameter name>,
  "dataType": "GPString",
  "value": {
    "itemId": <item Id>,
    "url": <URL>
  }
}

JSON Response example

Use dark colors for code blocksCopy
{
  "paramName": "outRaster",
  "dataType": "GPString",
  "value": {
    "itemId": "f121390b85ef419790479fc75b493efd",
    "url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/ImageServer"
  }
}