ArcGIS REST API - ArcGIS Services - Query (Feature Service/Layer)

URL:http://<featurelayer-url>/query
Required Capability:Query
Version Introduced:10.0

Description

The Query operation is performed on a feature service layer resource. The result of this operation is either a feature set or an array of feature IDs (if returnIdsOnly is set to true).

While there is a limit to the number of features included in the feature set response, there is no limit to 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.

In the feature set response, the layer features include their geometries. The records for tables do not.

For time-aware layers, users can use the time parameter to specify the time instant or the time extent to query.

You can provide arguments to the Query operation defined in the following parameters table:

Request parameters

Parameter	Details
f	Description: The response format. The default response format is html. Values: html \| json \| amf (default, when returnIdsOnly=false and returnCountOnly=false) Values: html \| json (when returnIdsOnly=true or returnCountOnly=true)
where	Description: A where clause for the query filter. Any legal SQL where clause operating on the fields in the layer is allowed. Examples: where=POP2000 > 350000 where=CITY_NAME = 'Glendora'
objectIds	Description: The object IDs of this layer/table to be queried. Note: 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
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
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, see the documentation for the spatial relate function. Note: This parameter is not supported in the ArcGIS Online hosted service case.
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 result set. This list is a comma delimited list of field names. 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	This option was added at 10.1. Description: If true, the result includes the geometry associated with each feature returned. The default is true. Values: true \| false
maxAllowableOffset	This option was added at 10.1. 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 outSR. If outSR 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 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.
gdbVersion	//This option was added at 10.1. Description: Geodatabase version to query. This parameter applies only if the isDataVersioned property of the layer is true. If this is not specified, query will apply to the published map’s version. Syntax: gdbVersion=<version> Example: gdbVersion=SDE.DEFAULT
returnDistinctValues	Description: If true, then returns distinct values based on the fields specified in outFields. This parameter applies only if the supportsAdvancedQueries property of the layer is true. Values: <true \| false> Example: returnDistinctValues=true
returnIdsOnly	Description: If true, the response only includes an array of object IDs. Otherwise, the response is a feature set. The default is false. While there is a limit to the number of features included in the feature set response, there is no limit to 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. When objectIds are specified, setting this parameter to true is invalid. Values: true \| false
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: true \| false
orderByFields	This option was added at 10.1. Description: One or more field names on which the features/records need to be ordered. Use ASC or DESC for ascending or descending, respectively, following every field to control the ordering. Note: 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
groupByFieldsForStatistics	This option was added at 10.1. Description: One or more field names on which the values need to be grouped for calculating the statistics. Note: groupByFieldsForStatistics is valid only when the outStatistics parameter is used. Syntax: groupByFieldsForStatistics=field1, field2 Example: groupByFieldsForStatistics=STATE_NAME, GENDER
outStatistics	This option was added at 10.1. Description: The definitions for one or more field-based statistics to be calculated. Note: outStatistics is supported on only those layers/tables that indicate suppportsStatistics is true. If outStatisticFieldName is empty or missing, the map server assigns a field name to the returned statistic field. A valid field name can only contain alphanumeric characters and an underscore. When using outStatistics, the only other parameters that can be used are groupByFieldsForStatistics, orderByFields, time, and where. 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" } ]`
returnZ	This option was added at 10.1. Description: If true, Z values are included in the results if the features have Z values. Otherwise, Z values are not returned. The default is false. This parameter only applies if returnGeometry is true, and the layer's hasZ property is true.
returnM	This option was added at 10.1. Description: If true, M values are included in the results if the features have M values. Otherwise, M values are not returned. The default is false. This parameter only applies if returnGeometry is true, and the layer's hasM property is true .

Example usage

Example 1: Query using a WHERE clause
http://services.myserver.com/ERmEceOGq5cHrItq/ArcGIS/rest/services/Earthquakes/EarthquakesFromLastSevenDays/FeatureServer/0/query?where=magnitude+%3E+4.5&outFields=*&returnGeometry=true&returnIdsOnly=false&f=html
Example 2: Query a table using a WHERE clause and return OBJECTIDs only
http://services.myserver.com/ERmEceOGq5cHrItq/ArcGIS/rest/services/SanFrancisco/311Incidents/FeatureServer/1/query?where=agree_with_incident+%3D+1&returnGeometry=true&returnIdsOnly=true&f=html

JSON response syntax (when returnIdsOnly=false and returnCountOnly=false)

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

JSON response syntax (when returnCountOnly=true)

            
          
{
  "count" : <count>
}

JSON response syntax (when returnIdsOnly=true)

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

JSON response example (when returnIdsOnly=false and returnCountOnly=false)

            
          
{
  "objectIdFieldName" : "objectid",
  "globalIdFieldName" : "",
  "geometryType" : "esriGeometryPoint",
  "spatialReference" : {
    "wkid" : 4326
  },
    "fields" : [
    {
      "name" : "objectid", 
      "type" : "esriFieldTypeOID", 
      "alias" : "Object ID"
    }, 
    {
      "name" : "datetime", 
      "type" : "esriFieldTypeDate", 
      "alias" : "Earthquake Date",
      "length" : 36
    }, 
    {
      "name" : "depth", 
      "type" : "esriFieldTypeDouble", 
      "alias" : "Depth"
    }, 
    {
      "name" : "eqid", 
      "type" : "esriFieldTypeString", 
      "alias" : "Earthquake ID",
      "length" : 50
    }, 
    {
      "name" : "latitude", 
      "type" : "esriFieldTypeDouble", 
      "alias" : "Latitude"
    }, 
    {
      "name" : "longitude", 
      "type" : "esriFieldTypeDouble", 
      "alias" : "Longitude"
    }, 
    {
      "name" : "magnitude", 
      "type" : "esriFieldTypeDouble", 
      "alias" : "Magnitude"
    }, 
    {
      "name" : "numstations", 
      "type" : "esriFieldTypeInteger", 
      "alias" : "Number of Stations"
    }, 
    {
      "name" : "region", 
      "type" : "esriFieldTypeString", 
      "alias" : "Region", 
      "length" : 200
    }, 
    {
      "name" : "source", 
      "type" : "esriFieldTypeString", 
      "alias" : "Source", 
      "length" : 50
    }, 
    {
      "name" : "version", 
      "type" : "esriFieldTypeString", 
      "alias" : "Version",
      "length" : 50
    }
  ],
  "features" : [
    {
      "geometry" : {
        "x" : -178.24479999999991,
        "y" : 50.012500000000045
      },
      "attributes" : {
        "objectid" : 3745682,
        "datetime" : 1272210710000,
        "depth" : 31.100000000000001,
        "eqid" : "2010vma5",
        "latitude" : 50.012500000000003,
        "longitude" : -178.2448,
        "magnitude" : 4.7999999999999998,
        "numstations" : 112,
        "region" : "Andreanof Islands, Aleutian Islands, Alaska",
        "source" : "us",
        "version" : "Q"
      }
    },
    {
      "geometry" : {
        "x" : -72.865099999999927,
        "y" : -37.486599999999953
      },
      "attributes" : {
        "objectid" : 3745685,
        "datetime" : 1272210142999,
        "depth" : 40.600000000000001,
        "eqid" : "2010vma4",
        "latitude" : -37.486600000000003,
        "longitude" : -72.865099999999998,
        "magnitude" : 4.9000000000000004,
        "numstations" : 58,
        "region" : "Bio-Bio, Chile",
        "source" : "us",
        "version" : "7"
      }
    }
  ]
}

JSON response example (when returnIdsOnly=false, returnCountOnly=false, and outFields="")

            
          
{
  "objectIdFieldName" : "objectid",
  "globalIdFieldName" : "",
  "geometryType" : "esriGeometryPoint",
  "spatialReference" : {
    "wkid" : 4326
  },
  "fields" : [
    
  ],
  "features" : [
    {
      "geometry" : {
        "x" : 237.17180000000008,
        "y" : 38.844700000000046
      },
      "attributes" : {
        
      }
    },
    {
      "geometry" : {
        "x" : 242.89430000000004,
        "y" : 34.559200000000089
      },
      "attributes" : {
        
      }
    }
  ]
}

JSON response example (when returnIdsOnly=false, returnCountOnly=false, outFields="", and geometryPrecision=3)

            
          
{
  "objectIdFieldName" : "objectid",
  "globalIdFieldName" : "",
  "geometryType" : "esriGeometryPoint",
  "spatialReference" : {
    "wkid" : 4326
  },
  "fields" : [
    
  ],
  "features" : [
    {
      "geometry" : {
        "x" : 237.172,
        "y" : 38.845
      },
      "attributes" : {
        
      }
    },
    {
      "geometry" : {
        "x" : 242.894,
        "y" : 34.559
      },
      "attributes" : {
        
      }
    }
  ]
}

JSON response example (when returnIdsOnly=true)

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

JSON response example (when returnCountOnly=true)

            
          
{
  "count":48
}