Identify (Image Service)

Description

The identify operation is performed on an image service resource. It identifies the content of an image service for a given location and a given mosaic rule. The location can be a point or a polygon.

The identify operation is supported by both mosaic dataset and raster dataset image services.

The result of this operation includes the pixel value of the mosaic for a given mosaic rule, a resolution (pixel size), and a set of catalog items that overlap the given geometry. The single pixel value is that of the mosaic at the centroid of the specified location. If there are multiple rasters overlapping the location, the visibility of a raster is determined by the order of the rasters defined in the mosaic rule. It also contains a set of catalog items that overlap the given geometry. The catalog items are ordered based on the mosaic rule. A list of catalog item visibilities gives the percentage contribution of the item to overall mosaic.

You can provide arguments to the identify 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 to be identified. The location can be a point or polygon. The structure of the geometry is the same as the structure of the JSON geometry objects returned by the ArcGIS REST API. In addition to the JSON structures, for points, you can specify the geometry with a simple comma-separated syntax.

This is a required parameter. The default geometry type is a point. By default, the geometry is assumed to be in the spatial reference of the image service. You can specify a different spatial reference by using the JSON structure syntax for geometries.

Syntax:

  • JSON structures: geometryType=<geometryType>&geometry={geometry}
  • Point simple syntax: geometryType=esriGeometryPoint&geometry=<x>,<y>

Examples:

  • geometryType=esriGeometryPoint&geometry={x: -104, y: 35.6}
  • geometryType=esriGeometryPoint&geometry=-104,35.6

geometryType

Description: The type of geometry specified by the geometry parameter. The geometry type can be a point or polygon.

Values: esriGeometryPoint | esriGeometryPolygon

mosaicRule

Description: Specifies the mosaic rule when defining how individual images should be mosaicked. When a mosaic rule is not specified, the default mosaic rule of the image service will be used (as advertised in the root resource: defaultMosaicMethod, mosaicOperator, sortField, sortValue).

See the mosaic rule JSON objects for the syntax and examples.

renderingRule

Added at 10.1.

Description: Specifies the rendering rule for how the requested image should be rendered.

See the raster function JSON objects for the syntax and examples.

pixelSize

Description: The pixel level being identified (or the resolution being looked at). If pixel size is not specified, then pixelSize will default to the base resolution of the dataset. The raster at the specified pixel size in the mosaic dataset will be used for identify.

The structure of the pixelSize 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.

Syntax:

  • JSON structure: pixelSize={point}
  • Point simple syntax: pixelSize=<x>,<y>

Examples:

  • pixelSize={x: 0.18, y: 0.18}
  • pixelSize=0.18,0.18

time

Added at 10.1.

Description: The time instant or time extent of the raster to be identified. This parameter is only valid if the image service supports time.

Time instant

  • Syntax: time=<timeInstant>

  • Example: time=1199145600000 (1 Jan 2008 00:00:00 GMT)

Time extent (For time extents where <startTime> or <endTime>, but not both, are null.)

Syntax: time=<startTime>, <endTime>

  • Example: time=1199145600000, 1230768000000 (1 Jan 2008 00:00:00 GMT to 1 Jan 2009 00:00:00 GMT)

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

returnGeometry

Added at 10.1.

Description: Indicates whether or not to return the raster catalog item's footprint. Set it to false when the catalog item's footprint is not needed to improve the identify operation's response time.

Syntax: returnGeometry=<true | false>

Example: returnGeometry=false

returnCatalogItems

Added at 10.1.

Description: Indicates whether or not to return raster catalog items. Set it to false when catalog items are not needed to improve the identify operation's performance significantly. When set to false, neither the geometry nor attributes of catalog items will be returned.

Syntax: returnCatalogItems=<true | false>

Example: returnCatalogItems=false

Example usage

Example 1: Identify a single raster Image Service using a point geometry.

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Earthquakes/SanAndreasLidar/ImageServer/identify?geometry={"x":575505.5,"y":3733770}&geometryType=esriGeometryPoint&mosaicRule=&pixelSize=0.5,0.5&f=pjson

Example 2: Identify a mosaic dataset Image Service using a polygon geometry and specify mosaic rule using esriMosaicAttribute method.

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Portland/CascadeLandsat/ImageServer/identify?geometry={"rings": [[[-13555360.4191,5911556.581],[-13489311.5669, 5898227.932],[-13423477.4153,5884426.3329],[-13602646.9571, 5717848.4135], [-13587119.9125, 5781976.6214],[-13571360.1713, 5846543.2654],[-13555360.4191, 5911556.581]]]}&geometryType=esriGeometryPolygon&mosaicRule={"mosaicMethod" : "esriMosaicAttribute","where" : "Name NOT LIKE 'Ov%'","sortField" : "Name","mosaicOperation" : "MT_MAX"}&pixelSize={"x":14.25,"y":14.25}&f=pjson

Example 3: Identify an elevation service using a point geometry and not to return catalog items.

http://sampleserver6.arcgisonline.com/arcgis/rest/services/CharlotteLAS/ImageServer/identify?geometry={"x":1446235.490173543,"y":542459.4874152396,"spatialReference":{"wkid":102719}}&geometryType=esriGeometryPoint&mosaicRule=&renderingRule=&pixelSize=&time=&returnGeometry=false&returnCatalogItems=false&f=pjson

JSON response syntax

{
"objectId" : <objectId>,
"name" : "<name>",
"value" : "<pixelValue>",
"location" : <point>, //the identified location
"properties" : { //the properties of the identified object. (returned only when the image service source is from a mosaic dataset)
  "name1" : <value1>,
  "name2" : <value2>
},
//catalogItems are returned only when the image service source is a mosaic dataset.
"catalogItems" : {
  "objectIdFieldName" : "<objectIdFieldName>",
  "spatialReference" : <spatialReference>,
  "geometryType" : "<geometryType>",
  "features" : [ 
    <feature1>, <feature2>
  ]
},
//catalogItemVisibilities are returned only when the image service source is a mosaic dataset.
"catalogItemVisibilities" : [ <catalogItem1Visibility>, <catalogItem2Visibility> ]
}

//note: the "Values" property in "properties" contain array of pixel values for individual rasters, arranged in the order of catalogItems.
//e.g. {"Values":["pixelvalue_raster1","pixelvalue_raster2",...]}

JSON response example 1

{
  "objectId" : 0, 
  "name" : "Pixel", 
  "value" : "-17.5575", 
  "location" : 
  {
    "x" : 575505.5, 
    "y" : 3733770, 
    "spatialReference" : {
      "wkid" : 26911
    }
  }, "properties" : null, 
  "catalogItems" : null, 
  "catalogItemVisibilities" : []
}

JSON response example 2

{
  "objectId" : 0, 
  "name" : "Pixel", 
  "value" : "17, 22, 39, 45", 
  "location" : 
  {
    "x" : -13527177.6374152, 
    "y" : 5837991.41167063, 
    "spatialReference" : {
      "wkid" : 54004
    }
  }, 
  "properties" : 
  {
    "Values" : [
      "10 18 34 43", //band values are space delimited
      "17 22 39 45"
    ]
  }, 
  "catalogItems" : 
  {
    "objectIdFieldName" : "OBJECTID", 
    "spatialReference" : {
      "wkid" : 54004
    }, 
    "geometryType" : "esriGeometryPolygon", 
    "features" : [
      
      {
        "geometry" : 
        {
          "rings" : 
          [
            [
              [-13460551.7089, 5854521.5319], 
              [-13478287.1495, 5790460.0595], 
              [-13495758.3317, 5726819.8268], 
              [-13512973.0996, 5663593.4924], 
              [-13529939.0436, 5600773.8464], 
              [-13593636.8922, 5614581.7474], 
              [-13657532.2448, 5627959.8481], 
              [-13721616.7496, 5640902.1352], 
              [-13785881.8549, 5653402.7833], 
              [-13770610.5633, 5717098.1159], 
              [-13755121.9097, 5781227.8467], 
              [-13739408.9372, 5845800.1358], 
              [-13723464.45, 5910823.3172], 
              [-13657416.2669, 5897455.1875], 
              [-13591575.2527, 5883610.99], 
              [-13525950.7118, 5869297.4578], 
              [-13460551.7089, 5854521.5319]
            ]
          ]
        }, 
        "attributes" : 
        {
          "OBJECTID" : 6, 
          "Name" : "p046r028_7t19990907.met;p046r028_7t19990907.met", 
          "MinPS" : 0, 
          "MaxPS" : 28.5, 
          "LowPS" : 14.25, 
          "HighPS" : 114, 
          "Category" : 1, 
          "Tag" : "Pansharpened", 
          "GroupName" : "p046r028_7t19990907", 
          "ProductName" : "Level1", 
          "CenterX" : -13624980.3112093, 
          "CenterY" : 5756154.02144619, 
          "ZOrder" : null, 
          "SOrder" : null, 
          "StereoID" : "", 
          "SensorName" : "Landsat-7-ETM+", 
          "AcquisitionDate" : 936662400000, 
          "SunAzimuth" : 150.8831799, 
          "SunElevation" : 46.5205819, 
          "CloudCover" : 0, 
          "Shape_Length" : 1058133.67231272, 
          "Shape_Area" : 69904833443.6272
        }
      }, 
      {
        "geometry" : 
        {
          "rings" : 
          [
            [
              [-13292489.9099, 5855431.779], 
              [-13310286.7337, 5791381.4753], 
              [-13327810.7467, 5727748.1244], 
              [-13345069.9061, 5664524.4905], 
              [-13362071.9117, 5601703.4638], 
              [-13425742.0169, 5615460.9307], 
              [-13489617.0175, 5628791.9699], 
              [-13553688.6321, 5641690.4875], 
              [-13617948.3761, 5654150.574], 
              [-13602646.9571, 5717848.4135], 
              [-13587119.9125, 5781976.6214], 
              [-13571360.1713, 5846543.2654], 
              [-13555360.4191, 5911556.581], 
              [-13489311.5669, 5898227.932], 
              [-13423477.4153, 5884426.3329], 
              [-13357867.1993, 5870158.6064], 
              [-13292489.9099, 5855431.779]
            ]
          ]
        }, 
        "attributes" : 
        {
          "OBJECTID" : 2, 
          "Name" : "p045r028_7t19991002.met;p045r028_7t19991002.met", 
          "MinPS" : 0, 
          "MaxPS" : 28.5, 
          "LowPS" : 14.25, 
          "HighPS" : 114, 
          "Category" : 1, 
          "Tag" : "Pansharpened", 
          "GroupName" : "p045r028_7t19991002", 
          "ProductName" : "Level1", 
          "CenterX" : -13456998.9817332, 
          "CenterY" : 5756986.51347787, 
          "ZOrder" : null, 
          "SOrder" : null, 
          "StereoID" : "", 
          "SensorName" : "Landsat-7-ETM+", 
          "AcquisitionDate" : 938822400000, 
          "SunAzimuth" : 157.6031865, 
          "SunElevation" : 37.975699, 
          "CloudCover" : 50, 
          "Shape_Length" : 1058012.72377166, 
          "Shape_Area" : 69884678121.7441
        }
      }
    ]
  }, 
  "catalogItemVisibilities" : [
    0.671180049953907, 
    0.328819950035319
  ]
}

JSON response example 3

{
 "objectId": 0,
 "name": "Pixel",
 "value": "706.54",
 "location": {
  "x": 1446235.4901735431,
  "y": 542459.48741523956,
  "spatialReference": {
   "wkid": 102719,
   "latestWkid": 2264
  }
 },
 "properties": null,
 "catalogItems": null,
 "catalogItemVisibilities": [
  
 ]
}