FRAMES | NO FRAMES Description | Parameters | Examples | Response
Identify (Operation)
URL http://<mapservice-url>/identify
Parent Resource Map Service
Required Capability Query

Description

The identify operation is performed on a map service resource to discover features at a geographic location. The result of this operation is an identify results resource. Each identified result includes its name, layer ID, layer name, geometry and geometry type, and other attributes of that result as name-value pairs.

New in 10.1

New in 10.0

You can provide arguments to the identify operation as query parameters defined in the parameters table below.

Parameters

Parameter Details
f Description: The response format. The default response format is html.

Values: html | json
geometry Required
Description: The geometry to identify on. The type of the geometry is specified by the geometryType parameter. The structure of the geometries is same as the structure of the JSON geometry objects returned by the ArcGIS REST API. In addition to the JSON structures, for points and envelopes, you can specify the geometries with a simpler comma-separated syntax.

Syntax:
  • JSON structures: geometryType=<geometryType>&geometry={geometry}
  • Point simple syntax: geometryType=esriGeometryPoint&geometry=<x>,<y>
  • Envelope simple syntax: geometryType=esriGeometryEnvelope&geometry=<xmin>,<ymin>,<xmax>,<ymax>
Examples:
  • geometryType=esriGeometryPoint&geometry={x: -104, y: 35.6}
  • geometryType=esriGeometryPoint&geometry=-104,35.6
  • geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41

The coordinates must always use a period as the decimal separater even in countries where a comma is traditionally used.
geometryType Description: The type of geometry specified by the geometry parameter. The geometry type could be a point, a line, a polygon or an envelope. The default geometry type is a point (esriGeometryPoint).

Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope
sr Description: The well-known ID of the spatial reference of the input and output geometries as well as the mapExtent. If sr is not specified, the geometry and the mapExtent are assumed to be in the spatial reference of the map, and the output geometries are also in the spatial reference of the map.
layerDefs (New in 10)

Description: Allows you to filter the features of individual layers in the exported map by specifying definition expressions for those layers. Definition expression for a layer that is published with the service will be always honored.

Simple Syntax:

Syntax: layerId1:layerDef1;layerId2:layerDef2
where layerId1, layerId2 are the layer ids returned by the map service resource

Example: 0:POP2000 > 1000000;5:AREA > 100000

JSON Syntax:

You can also use a JSON representation for Layer Definitions.

Syntax:
{ "<layerId1>" : "<layerDef1>" , "<layerId2>" : "<layerDef2>" }
where layerId1, layerId2 are the layer ids returned by the map service resource

Example:
{"0":"POP2000 > 1000000","5":"AREA > 100000"}
time //This parameter was added at 10.0

Description: The time instant or the time extent of the features to be identified.

Time instant

Syntax: time=<timeInstant>
Example: time=1199145600000 (1 Jan 2008 00:00:00 GMT)

Time extent

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.
layerTimeOptions //This parameter was added at 10.0

Description: The time options per layer. Users can indicate whether or not the layer should use the time extent specified by the time parameter or not, whether to draw the layer features cumulatively or not and the time offsets for the layer.

Syntax: 
{
  "<layerId1>" : {
    //If true, use the time extent specified by the time parameter
    "useTime" : < true | false >,
    //If true, draw all the features from the beginning of time for that data
    "timeDataCumulative" : < true | false >,
    //Time offset for this layer so that it can be overlaid on the top of a previous or future time period
    "timeOffset" : <timeOffset1>,
    "timeOffsetUnits" : "<esriTimeUnitsCenturies | esriTimeUnitsDays | esriTimeUnitsDecades | 
                             esriTimeUnitsHours | esriTimeUnitsMilliseconds | esriTimeUnitsMinutes | 
                             esriTimeUnitsMonths | esriTimeUnitsSeconds | esriTimeUnitsWeeks | esriTimeUnitsYears |
                             esriTimeUnitsUnknown>"
  },
  "<layerId2>" : {
    "useTime" : < true | false >,
    "timeDataCumulative" : < true | false >,
    "timeOffsetOffset" : <timeOffset2>,
    "timeOffsetUnits" : "<timeOffsetUnits2>"
  }
}
Example: 
{
  "0" : {
    "useTime" : true,
    "timeDataCumulative" : false,
    "timeOffset" : 1,
    "timeOffsetUnits" : "esriTimeUnitsYears"
  },
  "3" : {
    "useTime" : false
  }
}
layers Description: The layers to perform the identify operation on. There are three ways to specify which layers to identify on:
  • top: Only the top-most layer at the specified location.
  • visible: All visible layers at the specified location.
  • all: All layers at the specified location.
Example: layers=all

Default: By default the identify operation identifies the top-most layer (i.e. layers=top)

You can either specify the layer options as mentioned above by themselves or specify the layer option in conjunction with a list of layer IDs. When both the layer option as well as the layer IDs are specified, the server treats it as a boolean "AND" operator. For example, if the parameter is specified as: layers=visible:2,5 only layers with IDs 2 and 5, if visible, are identified.

Syntax: [top | visible | all]:layerId1,layerId2
where layerId1, layerId2 are the layer ids returned by the map service resource.

Example: layers=visible:2,5

Note: In the case of dynamic layers the layer list is ignored, it instead uses top or all (default) to identify the layers defined in dynamicLayers parameter.

tolerance Required
Description: The distance in screen pixels from the specified geometry within which the identify should be performed. The value for the tolerance is an integer.

Example: tolerance=2
mapExtent Required
Description: The extent or bounding box of the map currently being viewed. Unless the sr parameter has been specified, the mapExtent is assumed to be in the spatial reference of the map.

The mapExtent and the imageDisplay parameters are used by the server to determine the layers visible in the current extent. They are also used to calculate the distance on the map to search based on the tolerance in screen pixels.

Syntax: <xmin>, <ymin>, <xmax>, <ymax>

Example: mapExtent=-104,35.6,-94.32,41
imageDisplay Required
Description: The screen image display parameters (width, height and DPI) of the map being currently viewed.

The mapExtent and the imageDisplay parameters are used by the server to determine the layers visible in the current extent. They are also used to calculate the distance on the map to search based on the tolerance in screen pixels.

Syntax: <width>, <height>, <dpi>

Example: imageDisplay=600,550,96
returnGeometry Description: If true, the resultset will include the geometries associated with each result. The default is true.

Values: true | false
maxAllowableOffset //This option was added at 10.0

Description: This option can be used to specify the maximum allowable offset to be used for generalizing geometries returned by the identify operation.

The maxAllowableOffset is in the units of the sr. If sr is not specified then maxAllowableOffset is assumed to be in the unit of the spatial reference of the map.

Example: maxAllowableOffset=2
geometryPrecision //This option was added at 10.1

Description: This option can be used to specify the number of decimal places in the response geometries returned by the identify operation.

This applies to X and Y values only (not m or z-values).

Example: geometryPrecision=3
dynamicLayers //This option was added at 10.1

Description: Use dynamicLayers property to reorder layers and change the layer data source. dynamicLayers can also be used to add new layer that was not defined in the map used to create the map service. The new layer should have its source pointing to one of the registered workspaces that was defined at the time the map service was created.

The order of dynamicLayers array defines the layer drawing order. The first element of the dynamicLayers array is stacked on top of all other layers.

When defining a dynamic layer source is required.

Syntax: 
[
  {
    "id": <layerOrTableId>,
    "source": <layer source>,
    "definitionExpression": "<definitionExpression>",
    "layerTimeOptions":
    {
      "useTime" : <true | false>,
      "timeDataCumulative" : <true | false>,
      "timeOffset" : <timeOffset>,
      "timeOffsetUnits" : "<esriTimeUnitsCenturies | esriTimeUnitsDays | esriTimeUnitsDecades | 
                             esriTimeUnitsHours | esriTimeUnitsMilliseconds | esriTimeUnitsMinutes | 
                             esriTimeUnitsMonths | esriTimeUnitsSeconds | esriTimeUnitsWeeks | esriTimeUnitsYears |
                             esriTimeUnitsUnknown>"
    }
  },
  {
    "id": <layerOrTableId>,
    "source": <layer source>,
    "definitionExpression": "<definitionExpression>",
    "layerTimeOptions":
    {
      "useTime" : <true | false>,
      "timeDataCumulative" : <true | false>,
      "timeOffset" : <timeOffset>,
      "timeOffsetUnits" : "<esriTimeUnitsCenturies | esriTimeUnitsDays | esriTimeUnitsDecades | 
                             esriTimeUnitsHours | esriTimeUnitsMilliseconds | esriTimeUnitsMinutes | 
                             esriTimeUnitsMonths | esriTimeUnitsSeconds | esriTimeUnitsWeeks | esriTimeUnitsYears |
                             esriTimeUnitsUnknown>"
    }
  }
]
Example: 
[
  //disable time on existing map service layer
  {
    "id": 501,
    "source":
    {
      "type": "mapLayer",
      "mapLayerId": 0
    },
    "layerTimeOptions":
    {
      "useTime": false
    }
  },
  //add a new layer from registered workspace
  {
    "id": 502,
    "source":
    {
      "type": "dataLayer",
      "dataSource":
      {
        "type": "table",
        "workspaceId": "MAP",
        "dataSourceName": "MAP.user1.Taxlots"
      }
    }
  },
  //change the Version of existing map service layer
  {
    "id": 503,
    "source":
    {
      "type": "mapLayer",
      "mapLayerId": 1,
      "version": "USER1"
    },
    "definitionExpression": "neighborhood = 'French Quarter'"
  }
]
returnZ //This option was added at 10.1

Description: If true, Z values will be included in the results if the features have Z values. Otherwise Z values are not returned. The default is false.

Note this parameter only applies if returnGeometry is true.
returnM //This option was added at 10.1

Description: If true, M values will be included in the results if the features have M values. Otherwise M values are not returned. The default is false.

Note this parameter only applies if returnGeometry is true.
gdbVersion //This option was added at 10.1

Description: Switch map layers to point to an alternate geodatabase version.

Syntax: gdbVersion=<geodatabase version>
Example: gdbVersion=sde.USER1

Example Usage

Example 1: Identify that includes geometry using simple point syntax, tolerance, map extent, and image display. Default values for geometry type, spatial reference, layers, and returnGeometry are used. The response is in HTML format:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/identify?geometryType=esriGeometryPoint&geometry=-120,40&tolerance=10&mapExtent=-119,38,-121,41&imageDisplay=400,300,96

Example 2: Identify that includes geometry using a JSON structure. The response is in JSON format:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/identify?geometryType=esriGeometryPoint&geometry={x: -120, y:40}&tolerance=10&mapExtent=-119,38,-121,41&imageDisplay=400,300,96&f=json

Example 3: Identify that specifies a specific layer. In this example, only layer 2 is desired. Since this is not the top layer, the syntax layer=all:2 is used:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/identify?geometryType=esriGeometryPoint&geometry={x: -120, y:40}&layers=all:2&tolerance=10&mapExtent=-119,38,-121,41&imageDisplay=400,300,96&returnGeometry=true

Example 4: Identify operation using dynamicLayers:

http://servicesbeta2.esri.com/arcgis/rest/services/Census/MapServer/identify?geometry={"rings":[[[-406686.615,151348.621],[-277679.963,210564.789],[-152903.038,82615.569],[-334781.268,46662.895],[-406686.615,151348.621]]],"spatialReference":{"wkid":102003}}&geometryType=esriGeometryPolygon&sr=102003&layers=all&layerDefs=&time=&layerTimeOptions=&tolerance=2&mapExtent=-574325.931693231,-211967.870311805,154917.862982949,393469.077966946&imageDisplay=1056,816,96&returnGeometry=true&maxAllowableOffset=&dynamicLayers=[{"id":101,"source":{"type":"mapLayer","mapLayerId":3}}]&returnZ=false&returnM=false&gdbVersion=&f=pjson

JSON Response Syntax

{
"results" : [
 {
 "layerId" : <layerId1>,
 "layerName" : "<layerName1>", 
 "value" : "<value1>", 
 "displayFieldName" : "<displayFieldName1>",
 "attributes" : {
  "<fieldName11>" : <fieldValue11>,
  "<fieldName12>" : <fieldValue12>
 },
 "geometryType" : "<geometryType1>",
"hasZ" : <true|false>, //added in 10.1
"hasM" : <true|false>, //added in 10.1
"geometry" : {<geometry1>}
 },
 {
 "layerId" : <layerId2>,
 "layerName" : "<layerName2>",
 "value" : "<value2>", 
 "displayFieldName" : "<displayFieldName1>",
 "attributes" : {
  "<fieldName21>" : <fieldValue21>,
  "<fieldName22>" : <fieldValue22>
 },
 "geometryType" : "<geometryType2>",
"hasZ" : <true|false>, //added in 10.1
"hasM" : <true|false>, //added in 10.1
 "geometry" : {<geometry2>}
 }
]
}

JSON Response Example

{
"results" : [
 {
 "layerId" : 3,
 "layerName" : "Cities",
 "value" : "Joe City",
 "displayFieldName" : "City Name",
 "attributes" : {
  "City Name" : "Joe City",
  "CLASS" : "city",
  "ST" : "CA"
 },
 "geometryType" : "esriGeometryPoint",
 "geometry" : { "x" : -118.375, "y" : 34.086, "spatialReference" : {"wkid" : 4326} }
 },
 {
 "layerId" : 59,
 "layerName" : "Parcel",
 "value" : "Parcel 649",
 "displayFieldName" : "NAME",
 "attributes" : {
  "NAME" : "Parcel 649",
  "SUB_REGION" : "Pacific",
  "STATE_ABBR" : "CA"
 },
 "geometryType" : "esriGeometryPolygon",
 "geometry" : { "spatialReference" : {"wkid" : 4326}, "rings" : [[[-118.35,32.81],[-118.42.806],[-118.511,32.892],[-118.35,32.81]]]}
 }
]
}