Get Samples

Description

The getSamples operation is performed on an image service resource.

The getSamples operation 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 1000, 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

Parameter

Details

f

Description: The response format. The default response format is html.

Values: html | json

geometry

(Required)

Description: A geometry that defines the location(s) 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)

Description: 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

Description: 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

Description: 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

Description: 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

Description: 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

Description: 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.

Syntax: esri_codephreturnFirstValueOnly=<true | false>

Example: esri_codephreturnFirstValueOnly=false

interpolation

This parameter was added at 10.3.

Description: The resampling method. Default is nearest neighbor.

Values: RSP_BilinearInterpolation | RSP_CubicConvolution | RSP_Majority | RSP_NearestNeighbor

outFields

This parameter was added at 10.3.

Description: 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

Example (wildcard usage): outFields=*

Example usage

Example 1: Sample multiple points.

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

Example 2: Sample pixel values along a given path.

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

10/6/2017