Skip To Content

Get Samples

  • URL:https://<imageservice-url>/getSamples
  • Required Capability:Image
  • Version Introduced:10.2

Description

The getSamples operation is performed on an image service resource and is supported by both mosaic dataset and raster dataset image services.

The result of this operation includes sample point locations, pixel values, and corresponding spatial resolutions of the source data for a given geometry. When the input geometry is a polyline, envelope, or polygon, sampling is based on sampleCount or sampleDistance; when the input geometry is a point or multipoint, the point or points are used directly.

The number of sample locations in the response is based on the sampleDistance or sampleCount parameter and cannot exceed the limit of the image service (the default is 1,000, which is an approximate limit).

The sample location that will be used is the intersection of the geometry and the raster item's footprints, which are filtered by the mosaicRule and the pixelSize.

You can provide arguments to the getSamples operation as query parameters defined in the following parameters table:

Request parameters

ParameterDetails
geometry

(Required)

A geometry that defines the locations to be sampled. The structure of the geometry is the same as the structure of the JSON geometry objects returned by the ArcGIS REST API. Applicable geometry types are point, multipoint, polyline, polygon, and envelope. When spatialReference is omitted in the input geometry, it will be assumed to be the spatial reference of the image service.

Syntax


//JSON structure
geometryType=<geometryType>&geometry={geometry}

//Point simple syntax
geometryType=esriGeometryPoint&geometry=<x>,<y>

Example

geometryType=esriGeometryPoint&geometry={"x": -104, "y": 35.6, "spatialReference":{"wkid":4326}}
geometryType

(Required)

The type of geometry specified by the geometry parameter. The geometry type can be point, multipoint, polyline, polygon, or envelope.

Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope

sampleDistance

The distance interval used to sample points from the provided path. The unit is the same as the input geometry. If neither sampleCount nor sampleDistance is provided, no densification can be done for paths (polylines), and a default sampleCount (100) is used for areas (polygons or envelopes).

Example

sampleDistance=1.25
sampleCount

The approximate number of sample locations from the provided path. If neither sampleCount nor sampleDistance is provided, no densification can be done for paths (polylines), and a default sampleCount (100) is used for areas (polygons or envelopes).

Example

sampleCount=20
mosaicRule

Specifies the mosaic rule defining the image sort order. Additional filtering can be applied to the WHERE clause and FIDs of a mosaic rule. See the mosaic rule JSON objects for the syntax and examples.

pixelSize

The raster that is visible at the specified pixel size in the mosaic dataset will be used for sampling. If pixelSize is not specified, the service's pixel size is used. The structure of the esri_codephpixelSize parameter is the same as the structure of the point object returned by the ArcGIS REST API. In addition to the JSON structure, you can specify the pixel size with a simple comma-separated syntax.

returnFirstValueOnly

Indicates whether to return all values at a point, or return the first non-NoData value based on the current mosaic rule. The default is true.

Values: true | false

interpolation

Added at 10.3. The resampling method. The default is nearest neighbor.

Values: RSP_BilinearInterpolation | RSP_CubicConvolution | RSP_Majority | RSP_NearestNeighbor

outFields

Added at 10.3. The list of fields to be included in the response. This list is a comma-delimited list of field names. You can also specify the wildcard character (*) as the value of this parameter to include all the field values in the results.

Example


outFields=Salinity,Time

//Wildcard usage
outFields=*
sliceId

Added at 10.9. The slice ID of the multidimensional raster. This parameter is available if the image service uses ArcObjects11 or ArcObjectsRasterRendering as the service provider.

Syntax

sliceId=<slice ID>

Example

sliceId=1
time

Added at 10.9. The time instant or time extent of the raster to be sampled. This parameter is only valid if the image service supports time and if the image service uses ArcObjects11 or ArcObjectsRasterRendering as the service provider.

Syntax


//Time instant
Syntax: time=<timeInstant>

//Time extent (for time extents where <startTime> or <endTime, but not both, are null)
time=<startTime>, <endTime>
Note:

A null value specified for start time or end time will represent infinity for start or end time, respectively.

Example


//Time instant (1 Jan 2008 00:00:00 GMT)
time=1199145600000

//Time extent (1 Jan 2008 00:00:00 GMT to 1 Jan 2009 00:00:00 GMT)
time=1199145600000, 1230768000000
f

The response format. The default response format is html.

Values: html | json

Example usage

Sample multiple points

https://myserver/arcgis/rest/services/myimage/ImageServer/getSamples?geometryType=esriGeometryMultipoint&geometry={"points":[[-97.06138,32.837],[-97.06133,32.836],[-97.06124,32.834],[-97.06127,32.832]],"spatialReference":{"wkid":4326}}&f=json

Sample pixel values along a given path

https://myserver/arcgis/rest/services/myimage/ImageServer/getSamples?geometryType=esriGeometryPolyline&geometry={"paths":[[[-97.06138,32.837],[-97.06133,32.836],[-97.06124,32.834],[-97.06127,32.832]],[[-97.06326,32.759],[-97.06298,32.755]]],"spatialReference":{"wkid":4326}}&sampleCount=20&f=json

JSON Response syntax


{
  "samples": [
    {
      "location": <point>, 
      "value": "<value1>";
      "rasterId": <rasterId>,
      "resolution": <resolution>,
      "locationId": <locationId1>,
      "attributes": {
        "fieldname1": <value>,
        ...
      }
    },  
    {
      "location": <point>, 
      "value": "<value2>";
      "rasterId": <rasterId>,
      "resolution": <resolution>,
      "locationId": <locationId2>,
      "attributes": {
        "fieldname1": <value>,
        ...
      }
    }
  ]
}

JSON Response example


{
  "samples": [
    {
      "location": {
        "x": -8844874,
        "y": 5401062,
        "spatialReference": {
          "wkid": 3857
        }
      },
      "value": "287,395,1228",
      "rasterId": 5,
      "resolution": 4,
      "locationId": 1
    },
    {
      "location": {
        "x": -8834874,
        "y": 5408062,
        "spatialReference": {
          "wkid": 3857
        }
      },
      "value": "855,926,1089",
      "rasterId": 2,
      "resolution": 1,
      "locationId": 2
    }
  ]
}