Query (Map Service\Layer)

Description

NoteNote:

Before 10.0, the query operation could only be performed on layers. From 10.0 onward, in addition to layers, the query operation can be performed on tables as well.

The result of this operation is a featureset. This featureset contains Feature objects including the values for the fields requested by the user. For layers, if you request geometry information, the geometry of each feature is also returned in the featureset. For tables, the featureset does not include geometries.

Note that all parameters related to geometry will be ignored when querying tables.

New in 10.3.1

NoteNote:

When not using the resultOffset and resultRecordCount parameters, the exceededTransferLimit property may also be included in the query results. In this case, the property will be true only if the number of records exceeds the maximum number configured by the server administrator.

New in 10.3

New in 10.2

New in 10.1 SP1

New in 10.1

New in 10.0 SP1

New in 10.0

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

Request Parameters

Parameter

Details

f

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

NoteNote:

f=kmz would always return Z values.

Values: html | json | kmz | amf (default, when returnIdsOnly=false and returnCountOnly=false)

Values: html | json | amf (when outStatistics is specified)

Values: html | json (when either returnIdsOnly=true or returnCountOnly=true is specified)

text

Description: A literal search text. If the layer has a display field associated with it, the server searches for this text in this field. This parameter is a short hand for a where clause of: where <displayField> like '%<text>%'. The text is case sensitive. This parameter is ignored if the where parameter is specified.

Example: text=Los

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:

  • 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 | esriSpatialRelRelation

relationParam

Description: The spatial relate function that can be applied while performing the query operation. An example for this spatial relate function is "FFFTTT***."

For more information on this spatial relate function, refer to the documentation for the spatial relate function.

where

Description: A where clause for the query filter. Any legal SQL where clause operating on the fields in the layer is allowed.

Example: where=POP2000 > 350000

When standardized queries are enabled, where = CHAR_LENGTH(cntry_name) > 18

objectIds

Description: The object IDs of this layer/table to be queried.

NoteNote:

There might be a drop in performance if the layer / table data source resides in an enterprise geodatabase and more than 1000 objectIds are specified.

Syntax: objectIds=<objectId1>, <objectId2>

Example: objectIds=37, 462

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:

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.

outFields

Description: The list of fields to be included in the returned resultset. This list is a comma delimited list of field names. If you specify the shape field in the list of return fields, it is ignored. 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.

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.

Values: true | false

maxAllowableOffset

//This option was added at 10.0.

Description: This option can be used to specify the maxAllowableOffset to be used for generalizing geometries returned by the query operation.

The maxAllowableOffset is in the units of the outSR. If outSR is not specified, 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 query operation. This applies to X and Y values only (not m- or z-values).

Example: geometryPrecision=3

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 map.

returnIdsOnly

Description: If true, the response only includes an array of object IDs. Otherwise the response is a feature set. The default is false.

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.

Values: false | true

returnCountOnly

//This option was added at 10.0 SP1.

Description: If true, the response only includes the count (number of features/records) 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

orderByFields

//This option was added at 10.1.

Description: One or more field names using the features/records that need to be ordered. Use ASC or DESC for ascending or desending order respectively.

NoteNote:

  • orderByFields is supported on only those layers/tables that indicate supportsAdvancedQueries is true.
  • orderByFields defaults to ASC (ascending order) if <ORDER> is unspecified.

Syntax: orderByFields=field1 <ORDER>, field2 <ORDER>, field3 <ORDER>

Example: orderByFields=STATE_NAME ASC, RACE DESC, GENDER

outStatistics

//This option was added at 10.1.

Description: The definitions for one or more field-based statistics to be calculated.

NoteNote:

  • outStatistics is supported on only those layers/tables that indicate supportsStatistics is true.
  • If outStatisticFieldName is empty or missing, then map server would assign a field name to the returned statistic field. A valid field name can only contain alpha-numberic characters and an underscore.
  • When outStatistics, the only other parameters that will be used are groupByFieldsForStatistics, orderByFields, text, time, and where.
  • At version 10.1, specifying geometry, objectIds, or gdbVersion parameters would return an error.
  • At version 10.1 SP1 support for geometry parameter was added.
  • At version 10.2 support for gdbVersion parameter was added.

Values: An array of statistic definitions. A statistic definition specifies the type of statistic, the field on which it is to be calculated, and the resulting output field name.

Syntax:

[
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var>",
    "onStatisticField": "Field1", 
    "outStatisticFieldName": "Out_Field_Name1"
  },
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var>",
    "onStatisticField": "Field2",
    "outStatisticFieldName": "Out_Field_Name2"
  }  
]

Example:

[
  {
    "statisticType": "sum",
    "onStatisticField": "GENDER",
    "outStatisticFieldName": "PopulationByGender"
  },
  {
    "statisticType": "avg",
    "onStatisticField": "INCOME",
    "outStatisticFieldName": "AverageIncome"
  }
]

groupByFieldsForStatistics

//This option was added at 10.1.

Description: One or more field names using the values that need to be grouped for calculating the statistics.

NoteNote:

groupByFieldsForStatistics is valid only when outStatistics parameter is used.

Syntax: groupByFieldsForStatistics=field1, field2

Example: groupByFieldsForStatistics=STATE_NAME, GENDER

returnZ

//This option was added at 10.1.

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

NoteNote:

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.

NoteNote:

This parameter only applies if returnGeometry is true.

gdbVersion

//This option was added at 10.1.

Description: GeoDatabase version to query. This parameter applies only if hasVersionedData property of the service and isDataVersioned property of the layer(s) queried are true. If this is not specified, query will apply to published map's version.

Syntax: gdbVersion=<geodatabase version>

Example: gdbVersion=sde.USER1

returnDistinctValues

//This option was added at 10.1 SP1.

Description: If true, returns distinct values based on the fields specified in outFields. This parameter applies only if supportsAdvancedQueries property of the layer is true.

Syntax: returnDistinctValues=<true | false>

Example: returnDistinctValues=true

returnTrueCurves

//This option was added at 10.3.

Description: If true, returns true curves in output geometres, otherwise curves get converted to densified polylines or polygons.

Syntax: returnTrueCurves=<true | false>

Example: returnTrueCurves=true

resultOffset

//This option was added at 10.3.

Description: This option can be used for fetching query results by skipping the specified number of records and starts from the next record (i.e.resultOffset + 1th). The Default is 0.

This parameter only applies if supportsPagination is true.

You can use this option to fetch records that are beyond maxRecordCount.

For example, if maxRecordCountis 1000, you can get the next 100 records by setting resultOffset=1000 and resultRecordCount = 100, query results can return the results in the range of 1001 to 1100.

resultRecordCount

//This option was added at 10.3.

Description: This option can be used for fetching query results up to the resultRecordCount specified. When resultOffset is specified but this parameter is not, map service defaults it to maxRecordCount. The maximum value for this parameter is the value of the layer's maxRecordCount property.

This parameter only applies if supportsPagination is true.

Example: resultRecordCount=10 to fetch upto 10 records

Example Usage

Example 1: Query using the text parameter on the states layer of the ESRI_StateCityHighway_USA on sampleserver1:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/1/query?text=Texas

Example 2: Query using a where statement on the same layer. The output is JSON format:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/1/query?where=STATE_NAME='Florida'&f=json

Example 3: Query strings are case sensitive. In this example, UPPER is used to make the query case insensitive:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/1/query?where=UPPER(STATE_NAME)=UPPER('colorado')

Example 4: Querying the same states layer using geometry (envelope):

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/1/query?geometry=-125.4,35.2,-118.7,43.8&geometryType=esriGeometryEnvelope

Example 5: Querying the states layer by both geometry (envelope) and a where statement:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/1/query?geometry=-125.4,35.2,-118.7,43.8&geometryType=esriGeometryEnvelope&where=POP1999>5000000

Example 6: Querying the states layer by a where statement, specifying a list of fields to return, and requesting no geometry in the results:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/1/query?where=POP1999>15000000&returnGeometry=false&outFields=STATE_NAME,MALES,FEMALES,POP1999

Example 7: Querying the states layer by text parameter and requesting the geometry with the well-known ID of 102113 (Web Mercator):

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer/1/query?text=New+York&outSR=102113

Example 8: Query a table using a WHERE clause and return OBJECTIDs only:

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/SanFrancisco/311Incidents/MapServer/1/query?objectIds=&where=agree_with_incident+%3D+1&returnGeometry=true&returnIdsOnly=true&f=html

Example 9: Using groupByFieldsForStatistics and outStatistics:

http://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3/query?where=&text=&objectIds=&time=&geometry=&geometryType=esriGeometryEnvelope&inSR=&spatialRel=esriSpatialRelIntersects&relationParam=&outFields=&returnGeometry=true&maxAllowableOffset=&outSR=&returnIdsOnly=false&returnCountOnly=false&orderByFields=&groupByFieldsForStatistics=sub_region&outStatistics=[{%22statisticType%22:%22sum%22,%22onStatisticField%22:%22pop2007%22,%22outStatisticFieldName%22:%22Population_2007%22},{%22statisticType%22:%22avg%22,%22onStatisticField%22:%22AVE_FAM_SZ%22,%22outStatisticFieldName%22:%22Average_Family_Size%22}]&returnZ=false&returnM=false&gdbVersion=&f=pjson

Example 10: Page through a query result using resultOffset and resultRecordCount to get. Requesting to skip first 5 records and return next 10 counties in California order by population:

http://mymachine/arcgis/rest/services/USA/MapServer/3/query?where=STATE_NAME='California'&outFields=Name,Population&returnGeometry=false&resultOffset=5&resultRecordCount=10&orderByFields=Population&f=pjson

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

{
"displayFieldName" : "<displayFieldName>",
//fieldAliases deprecated at 10
"fieldAliases" : {
  "<fieldName1>" : "<fieldAlias1>",
  "<fieldName2>" : "<fieldAlias2>"
},
"fields" : [
    {"name" : "<fieldName1>", "type" : "<fieldType1>", "alias" : "<fieldAlias1>", "length" : "<length1>"},
    {"name" : "<fieldName2>", "type" : "<fieldType2>", "alias" : "<fieldAlias2>", "length" : "<length2>"}
],
"geometryType" : "<geometryType>", //for layers only
"spatialReference" : <spatialReference>, //for layers only
"hasZ" : <true|false>, //added in 10.1
"hasM" : <true|false>, //added in 10.1
"features" : [ //features may include geometry for layers only
  <feature1>, <feature2>
]
}

JSON Response Syntax (when returnIdsOnly=true)

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

JSON Response Syntax (when returnCountOnly=true)

{
"count" : <count>
}

JSON Response Syntax (when groupByFieldsForStatistics and outStatistics are specified)

{
"displayFieldName": "",
"fieldAliases": {
  "alias1": "fieldAlias1",
  "alias2": "fieldAlias2"
},
"fields":
[
  {
    "name": "fieldName1",
    "type": "fieldType1",
    "alias": "fieldAlias1", 
    "length": fieldLength1
  },
  {
    "name": "fieldName2",
    "type": "fieldType2",
    "alias": "fieldAlias2", 
    "length": fieldLength2
  }
],
"features": [<feature1>, <feature2>] //Feature object without geometry
}

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

{"displayFieldName" : "AREANAME",
"fieldAliases" : {    "ST" : "ST",    "POP2000" : "Population - 2000",    "AREANAME" : "City Name"
},
"fields" : [{    "name" : "ST",    "alias" : "ST",    "type" : "esriFieldTypeString",    "length" : 2},
{
    "name" : "POP2000",    "alias" : "Population - 2000",        "type" : "esriFieldTypeInteger"},
{    "name" : "AREANAME",    "alias" : "City Name",    "type" : "esriFieldTypeString",    "length" : 255}],
"geometryType" : "esriGeometryPoint","spatialReference" : {"wkid" : 4326},"features" : [    {    "attributes" : {        "ST" : "CA",        "POP2000" : 3694820,        "AREANAME" : "Los Angeles"    },    "geometry" : { "x" : -118.37, "y" : 34.086 }    },    {    "attributes" : {        "ST" : "CA",        "POP2000" : 461522,        "AREANAME" : "Long Beach"    },    "geometry" : { "x" : -118.15, "y" : 33.80 }    }]}

JSON Response Example (when returnIdsOnly=true)

{
"objectIdFieldName":"objectid",
"objectIds":[1,2,3,4,5,7]
}

JSON Response Example (when returnCountOnly=true)

{
"count":48
}

JSON Response Example (when groupByFieldsForStatistics and outStatistics are specified)

{
 "displayFieldName": "",
 "fieldAliases": {
  "sub_region": "SUB_REGION",
  "Population_2007": "Population_2007",
  "Average_Family_Size": "Average_Family_Size"
 },
 "fields": [
  {
   "name": "sub_region",
   "type": "esriFieldTypeString",
   "alias": "SUB_REGION",
   "length": 20
  },
  {
   "name": "Population_2007",
   "type": "esriFieldTypeDouble",
   "alias": "Population_2007"
  },
  {
   "name": "Average_Family_Size",
   "type": "esriFieldTypeDouble",
   "alias": "Average_Family_Size"
  }
 ],
 "features": [
  {
   "attributes": {
    "sub_region": "Pacific",
    "Population_2007": 49731702,
    "Average_Family_Size": 3.2439999999999998
   }
  },
  {
   "attributes": {
    "sub_region": "Mountain",
    "Population_2007": 21492235,
    "Average_Family_Size": 3.165
   }
  },
  {
   "attributes": {
    "sub_region": "New England",
    "Population_2007": 14515009,
    "Average_Family_Size": 3.0249999999999999
   }
  },
  {
   "attributes": {
    "sub_region": "West North Central",
    "Population_2007": 20384497,
    "Average_Family_Size": 3.044285714285714
   }
  },
  {
   "attributes": {
    "sub_region": "East North Central",
    "Population_2007": 47176974,
    "Average_Family_Size": 3.0940000000000003
   }
  },
  {
   "attributes": {
    "sub_region": "Middle Atlantic",
    "Population_2007": 41116339,
    "Average_Family_Size": 3.1566666666666663
   }
  },
  {
   "attributes": {
    "sub_region": "South Atlantic",
    "Population_2007": 58943344,
    "Average_Family_Size": 3.0333333333333332
   }
  },
  {
   "attributes": {
    "sub_region": "East South Central",
    "Population_2007": 18077309,
    "Average_Family_Size": 3.0275000000000003
   }
  },
  {
   "attributes": {
    "sub_region": "West South Central",
    "Population_2007": 34910821,
    "Average_Family_Size": 3.1124999999999998
   }
  }
 ]
}