How to Use the ArcGIS REST API Query Endpoint

The `/query` endpoint is the most powerful part of the ArcGIS REST API. It allows you to filter, sort, and extract data from a Feature Service. This guide covers the essential parameters for building complex queries.

The Anatomy of a Query URL

A query URL consists of a base URL and a set of key-value pairs.

https://services.arcgis.com/.../FeatureServer/0/query?where=1=1&outFields=*&f=json

Attribute Queries (The `where` clause)

The `where` parameter allows you to filter features using SQL syntax.

• Return all: where=1=1
• Text match: where=STATUS = 'Active'
• Numeric match: where=POPULATION > 50000
• Multiple conditions: where=TYPE = 'Residential' AND VALUE > 200000

Spatial Queries (Geometry and SpatialRel)

You can filter features based on their spatial relationship to a geometry. This is useful for extracting data within a specific bounding box or polygon.

&geometry=-95.99,36.15,-95.98,36.16&geometryType=esriGeometryEnvelope&spatialRel=esriSpatialRelIntersects&inSR=4326

This returns only the features that intersect the specified bounding box.

Output Control (outFields and returnGeometry)

To optimize performance, only request the fields you need.

• outFields=*: Returns all columns.
• outFields=NAME,POPULATION: Returns specific columns.
• returnGeometry=false: Drops the spatial data, returning only a table.

Pagination (resultOffset and resultRecordCount)

ArcGIS servers limit the number of features returned in a single request (usually 1,000 or 2,000). To get all data, you must paginate.

1. Set resultRecordCount=1000.
2. Set resultOffset=0 for the first request.
3. Increment the offset by 1000 for subsequent requests (e.g., resultOffset=1000, 2000).
4. Stop when the number of returned features is less than the requested count.

Format (`f` parameter)

• f=json: Returns ArcGIS JSON format.
• f=geojson: Returns standard GeoJSON (not always supported).
• f=pjson: Pretty-printed JSON (useful for debugging).

Common Errors

• Invalid URL: Check for unencoded spaces or quotes.
• Field not found: Ensure the field name is correct and case-sensitive.
• Token required: The service is secured.

Summary

Mastering the query endpoint is essential for any GIS developer working with ArcGIS REST services. By combining attribute and spatial filters, you can extract exactly the data you need with precision.