Skip To Content

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.

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

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>]}
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


outputName={"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


resamplingType=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


uniqueIdField=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 the following:

  • 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


statisticsType=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


percentileValue=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


bufferDistance=10

Syntax: A string representing the buffer distance field in the inLocationData.

Example 2


bufferDistance=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


layout=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.

Values: true | false

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.
  • Mask (mask)—Only cells that fall within the analysis mask will be considered in the operation.
  • 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.
  • Process as Multidimensional (processAsMultidimensional)—A Boolean that determines how the input rasters will be processed. This option is only available when the input is a single, multidimensional raster. The default value is False.

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

  • Resampling Method (resamplingMethod)—Specifies the resampling method that will be used when creating the raster dataset for download.
    • NEAREST—The value of the closest cell will be used to assign a value to the output cell when resampling. This is the default.
    • BILINEAR—The new value of a cell will be based on a weighted distance average of the four nearest input cell centers.
    • CUBIC—The new value of a cell will be based on fitting a smooth curve through the 16 nearest input cell centers.

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 Check 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": "https://<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"
  }
}

Related topics