FRAMES | NO FRAMES Description | Parameters | Examples | Response
Query - Image Service (Operation)
URL http://<imageservice-url>/query
Parent Resource Image Service
Required Capability Catalog

Description

The query operation is performed on an image service resource. It queries the raster catalog by applying the filter specified by the user. The result of this operation is either a set of features in the raster catalog or an array of raster ids (if returnIdsOnly is set to true).

Note that while there is a limit on the number of features included in the feature set response, there is no limit on the number of object IDs returned in the ID array response. Clients can exploit this to get all the query conforming object IDs by specifying returnIdsOnly=true and subsequently requesting feature sets for subsets of object IDs.

You can provide arguments to the query 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
objectIds Description: The object IDs of this raster catalog to be queried.

Note that when this parameter is specified, any other filter parameters (including where) are ignored.

When this parameter is specified, setting returnIdsOnly=true is invalid.

Syntax: objectIds=<objectId1>, <objectId2>

Example: objectIds=37, 462
where Description: A where clause for the query filter. Any legal SQL where clause operating on the fields in the raster catalog is allowed.

Example: where=POP2000 > 350000
time Description: The time instant or the time extent to query.

Time instant

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

Time extent (For time extents one of <startTime> or <endTime> could be '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.
geometry Description: The geometry to apply as the spatial filter. 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 envelopes and points, you can specify the geometry with a simpler comma-separated syntax.

Syntax:
  • JSON structures: geometryType=<geometryType>&geometry={geometry}
  • Envelope simple syntax: geometryType=esriGeometryEnvelope&geometry=<xmin>,<ymin>,<xmax>,<ymax>
  • Point simple syntax: geometryType=esriGeometryPoint&geometry=<x>,<y>
Examples:
  • geometryType=esriGeometryEnvelope&geometry={xmin: -104, ymin: 35.6, xmax: -94.32, ymax: 41}
  • geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41
  • geometryType=esriGeometryPoint&geometry=-104,35.6
geometryType Description: The type of geometry specified by the geometry parameter. The geometry type can be an envelope, point, line, or polygon. The default geometry type is an envelope.

Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope
inSR Description: The spatial reference of the input geometry.

The spatial reference can be specified as either a well-known ID or as a spatial reference json object.

If the inSR is not specified, the geometry is assumed to be in the spatial reference of the map.
spatialRel Description: The spatial relationship to be applied on the input geometry while performing the query. The supported spatial relationships include intersects, contains, envelope intersects, within, etc. The default spatial relationship is intersects (esriSpatialRelIntersects).

Values: esriSpatialRelIntersects | esriSpatialRelContains | esriSpatialRelCrosses | esriSpatialRelEnvelopeIntersects | esriSpatialRelIndexIntersects | esriSpatialRelOverlaps | esriSpatialRelTouches | esriSpatialRelWithin
outFields Description: The list of fields to be included in the returned resultset. This list is a comma delimited list of field names. To request geometry, set returnGeometry to true.

You can also specify the wildcard "*" as the value of this parameter. In this case, the query results include all the field values. Note that the wildcard also implicitly implies returnGeometry=true and setting returnGeometry to false will have no effect.

Example: outFields=AREANAME,ST,POP2000
Example (wildcard usage): outFields=*
returnGeometry Description: If true, the resultset includes the geometry associated with each result. The default is true.

Note that if the outFields parameter is set to the wildcard "*", it implicitly implies returnGeometry=true and setting returnGeometry to false has no effect.

Values: true | false
outSR Description: The spatial reference of the returned geometry.

The spatial reference can be specified as either a well-known ID or as a spatial reference json object.

If outSR is not specified, the geometry is returned in the spatial reference of the image service.
returnIdsOnly Description: If true, the response only includes an array of raster IDs. Otherwise the response is a raster set. The default is false.

Note that while there is a limit on the number of rasters included in the raster set response, there is no limit on the number of raster IDs returned in the ID array response. Clients can exploit this to get all the query conforming raster IDs by specifying returnIdsOnly=true and subsequently requesting raster sets for subsets of raster IDs.

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

Description: If true, the response only includes the count (number of features) that would be returned by a query. Otherwise the response is a feature set. The default is false. This option supersedes the returnIdsOnly parameter.

Values: false | true

Example Usage

Example 1: Query using a where clause and return specific outfields.

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Portland/CascadeLandsat/ImageServer/query?where=Name LIKE 'p045r028%' AND Name NOT LIKE 'Ovr%'&outFields=Name,MinPS,MaxPS,LowPS,HighPS&returnGeometry=true&returnIdsOnly=false&f=html

Example 2: Query using a point geometry and a where clause. Return only OBJECTIDs.

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Portland/CascadeLandsat/ImageServer/query?where=NAME NOT LIKE 'Ov_%'&geometry={"x":-122.895114,"y":45.558214,"spatialReference":{"wkid":4269}}&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&outFields=*&returnGeometry=false&returnIdsOnly=true&f=html

JSON Response Syntax (when returnIdsOnly=false and returnCountOnly=false)

{
"objectIdFieldName" : "<objectIdFieldName>",
"spatialReference" : <spatialReference>,
"fields" : [
    {"name" : "<fieldName1>", "type" : "<fieldType1>", "alias" : "<fieldAlias1>", "length" : "<length1>"},
    {"name" : "<fieldName2>", "type" : "<fieldType2>", "alias" : "<fieldAlias2>", "length" : "<length2>"}
],
"features" : [ 
  <feature1>, <feature2>
]
}

JSON Response Syntax (when returnCountOnly=true)

{
"count" : <count>
}

JSON Response Syntax (when returnIdsOnly=true)

{
"objectIdFieldName" : "<objectIdFieldName>",
"objectIds" : [ <objectId1>, <objectId2> ]
}

JSON Response Example

{
"objectIdFieldName" : "IMAGEID",
"spatialReference" : {"wkid" : 4326},

"fields" : [
{
    "name" : "ST",
    "alias" : "ST",
    "type" : "esriFieldTypeString",
    "length" : 2
},
{

    "name" : "OBJECTID",
    "alias" : "OBJECTID",
    "type" : "esriFieldTypeOID"
},

{
    "name" : "AREANAME",
    "alias" : "City Name",
    "type" : "esriFieldTypeString",
    "length" : 255
}
],
"geometryType" : "esriGeometryPolygon",
"features" : [
  {
    "geometry" : {
      "rings" : [ 
         [ [-97.06138,32.837], [-97.06133,32.836], [-97.06124,32.834], [-97.06127,32.832], [-97.06138,32.837] ]
      ]
    },
    "attributes" : {
      "IMAGEID" : 37,
      "OWNER" : "Joe Smith",
      "VALUE" : 94820.37,
      "APPROVED" : true,
      "LASTUPDATE" : 1227663551096
    }
  },
  {
    "geometry" : {
      "rings" : [ 
         [ [-97.06326,32.759], [-97.06298,32.755], [-97.06153,32.749], [-97.06326,32.759] ]
      ]
    },
    "attributes" : {
      "IMAGEID" : 462,
      "OWNER" : "John Doe",
      "VALUE" : 17325.90,
      "APPROVED" : false,
      "LASTUPDATE" : 1227628579430
    }
  }
]
}

JSON Response Example (when returnCountOnly=true)

{
"count":48
}