Skip To Content ArcGIS for Developers Sign In Dashboard

Sample

Description

Sample

The Sample task creates a table of cell values from a raster, or set of rasters, for defined locations. The locations are defined by raster cells, polygon features, polyline features, or by a set of points.

The input rasters can be two-dimensional or multidimensional. The structure of the output table changes when the input rasters are multidimensional.

License:
You must license your ArcGIS Server as an ArcGIS Image Server to use this resource.

Request parameters

ParameterDetails
inRasters

(Required)

List of input rasters. The input raster can be the Portal Item ID, Image Service URL, cloud raster dataset or shared multidimensional raster dataset.

Syntax: List of JSON object describing the input rasters.

inputMultidimensionalRaster={"itemIds": [<portal item id>, <portal item id>, <portal item id>]}
inputMultidimensionalRaster={"urls": [<image service url>, <image service url>, <image service url>]}
inputMultidimensionalRaster={"uris": [<cloud raster uri or shared data path>, <cloud raster uri or shared data path>]}

At least one type of input needs to be provided in the JSON object. If multiple inputs are given, the itemIds takes the priority.

inLocationData

(Required)

Data identifying positions where you want a sample taken.

The input can be an image service or a feature service.

Syntax: JSON object describing the input raster or feature. At least one type of input needs to be provided in the JSON object. If multiple inputs are given, the itemid takes the priority.

Example

"itemId": <portal item id>}
{“url”: <image service or feature service url>}
{“uri”: <cloud raster uri or shared data path>}

outputName

(Required)

Name of the output table or feature service holding the sampled cell values.

Syntax: JSON object describing the output table

Example

{"serviceProperties": {“name”:”sample_output”}}

resamplingType

Resampling algorithm used when sampling a raster.

  • NEAREST—Nearest neighbor assignment. This is the default.
  • BILINEAR—Bilinear interpolation
  • CUBIC—Cubic convolution

Syntax: A string representing the resamplingType.

Example

NEAREST

uniqueIdField

A field containing a different value for every location or feature in the input location raster or point features.

Syntax: A string representing the field.

Example

FID

acquisitionDefinition

Specify the time, depth or other acquisition data associated with the location features.

Statistics will be calculated for variables within the dimension range of the following combinations:

  • Dimension + Start field or value
  • Dimension + Start field or value + End field or value
  • Dimension + Start field or value + Relative value or days before + Relative value or days after

Only non-negative values are supported for:

  • Relative value or days before
  • Relative value or days after

Syntax: a list of dictionary objects.

[{"dimension":  "Dimension",
"startFieldOrVal": "Start field or value", 
"endFieldOrVal": "End field or value", 
"relValOrDaysBefore": "Relative value or days before", "relValOrDaysAfter": "Relative value or days after"}]

Example

[{"dimension":  "Dimension",
"startFieldOrVal": "1999-01-01T00:00:00", 
"endFieldOrVal": "2019-01-01T00:00:00"}]

statisticsType

The type of statistic to be calculated.

  • MINIMUM—Finds the minimum value within the specified range.
  • MAXIMUM—Finds the maximum value within the specified range.
  • MEDIAN—Finds the median value within the specified range.
  • MEAN—Calculates the average for the specified range.
  • SUM—Calculates the sum of the variables within the specified range.
  • MAJORITY—Finds the value that occurs most frequently.
  • MINORITY—Finds the value that occurs least frequently.
  • STD—Calculates the standard deviation.
  • PERCENTILE—Calculates a defined percentile within the specified range.

A string representing the statisticsType.

Example

MINIMUM

percentileValue

The percentile to calculate when the statisticsType parameter is set to PERCENTILE.

This value can range from 0 to 100. The default is 90.

Syntax: A double representing the percentileValue.

Example

50

bufferDistance

The specified distance around the location data features. The buffer distance is specified in the linear unit of the location feature's spatial reference. If the feature uses a geographic reference, the unit will be in degrees.

Statistics will be calculated within this buffer area.

Syntax: A value representing the bufferDistance.

Example 1

10

A string representing the buffer distance field in the inLocationData.

Example 2

buffer_field

layout

Specifies whether sampled values appear in rows or columns in the output table.

  • ROW_WISE—Sampled values appear in separate rows in the output table. This is the default.
  • COLUMN_WISE—Sampled values appear in separate columns in the output table. This option is only valid when the input multidimensional raster contains one variable and one dimension, and each slice is a single-band raster.

Syntax: A string of one of the keywords.

Example

COLUMN_WISE

generateFeatureClass

Boolean value to determine if this tool generates an output feature service containing a feature class with sampled values or only a table with sampled values. The default is false.

Syntax: A Boolean value as either true or false.

Example

generateFeatureClass =true

context

(Optional)

Contains additional settings that affect task execution. 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.
  • Parallel Processing Factor (parallelProcessingFactor)—The specified number or percentage of processes will be used for the analysis.
  • Mask (mask): Only cells that fall within the analysis mask will be considered in the operation.
  • Process as Multidimensional (processAsMultidimensional)— Boolean that Determines how the input rasters are processed. This option is only available when the input is a single, multidimensional raster. Default is False for this tool.

    True: Samples will be taken for all dimensions (such as time or depth) of a multidimensional dataset.

    False: Samples will be taken from the current slice of a multidimensional dataset. This is the default.

Example

context={"parallelProcessingFactor": "4"}
f

The response format. The default response format is html.

Values: html | json

Response

When you submit a request, the task 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 the 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:

https://<analysis url>/Sample/jobs/<jobId>

Accessing results

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

https://<raster analysis url>/Sample/jobs/<jobId>/results/outSample?token=<your token>&f=json

ParameterDescription
outSample

The output feature service itemId and URL

Example:

{"url": 
"http://<raster analysis url>/Sample/jobs/<jobId>/results/outSample"}

The result has properties for parameter name, data type, and value. The content of the value is always the output raster dataset's itemId and image service URL.

{
 "paramName": "outSample",
 "dataType": "GPString",
 "value": {
  "itemId": "c267610d0feb4370bf38cc6e2c4ac261",
  "url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/FeatureServer"
 }
}