Feature service

A feature service is a type of data service that stores spatial data (features) and non-spatial data. It provides access to the data with feature layers and tables. You use SQL queries, spatial queries, or a combination of both to get data from a feature service. Feature services are created and managed using data management tools and are accessed with a REST API.

Mapping applications typically use client APIs and feature services to access, query, edit, analyze and display data in a map or scene.

Bike parking and bike route data stored in feature services

Key features

  • Securely store spatial and non-spatial data in ArcGIS.
  • Access, edit (create, update, and delete), and analyze data.
  • Efficiently serve features with geometry and attributes to display in maps and scenes.
  • Query and filter data.
  • Analyze data.
  • Manage and share data.
  • Access, edit, analyze and view data in maps and scenes while offline.
  • Store and manage attachments (such as photographs or documents) linked to individual data records.
  • Easily created and managed as hosted feature layers in ArcGIS.

How to use a feature service

You typically use a feature service, feature layers, and tables by:

  1. Creating a feature service using data management tools.
  2. Accessing the feature service's feature layers and tables.
  3. Getting data from a feature layer or table for display, editing, or analysis.

How a feature service works

A feature service is accessed using the base service URL and consists of:

  • Feature layers for storing, accessing, and editing features.
  • Tables for storing, accessing, and editing non-spatial data.
  • Properties that describe the feature service and its capabilities, such as:
    • The spatial reference used to store geographic data in any feature layers.
    • A default geographic extent for viewing feature data.
    • A bounding geographic extent for feature data across all feature layers.
    • Description.
    • Copyright text.
    • Is editing supported?
    • Can the service be used offline?

A feature service also provides:

  • A REST API for programmatic access.
  • A web page for exploring and interacting with the feature service and its feature layers and tables.
  • Operations for working offline with data stored in the feature service.

Most typical interactions with a feature service are through individual feature layers and tables. You use the feature layers and tables to access, view, edit, and manage the data stored in the feature service.

Feature service URL

Feature services only support an enhanced endpoint. To access a feature service, use the host, unique service ID, and service name.

Use dark colors for code blocksCopy
Ā 
1
https://<host>/<uniqueID>/ArcGIS/rest/services/<serviceName>/FeatureServer/

For example:

Use dark colors for code blocksCopy
Ā 
1
https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/arcgis/rest/services/Mobile_Data_Collection_WFL1/FeatureServer

Learn more about standard and enhanced endpoints in Service endpoints.

NameDescriptionExamples
fThe format of the data returned.f=json f=pjson
tokenAn API key or OAuth 2.0 access token. Learn how to get an access token in Security and authentication.token=<YOUR_API_KEY>
token=<ACCESS_TOKEN>

Code examples

View a feature service web page

Explore a feature service by visiting its web page:

Get feature layers and tables

Get the feature service description properties for this service as formatted JSON, including the list of feature layer and tables provided by the feature service.

The service is shared with everyone, so no token is required.

Use dark colors for code blocksCopy
Ā 
1
https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/arcgis/rest/services/Mobile_Data_Collection_WFL1/FeatureServer?f=pjson

Feature layers and tables

A feature service contains one or more feature layers and/or tables. Feature layers provide access to spatial data. Tables provide access to non-spatial data.

Each feature layer and table is accessed with a URL that returns properties describing the feature layer or table. Some key properties are:

  • Feature layer or table name
  • ID field
  • Query capabilities
  • Edit permissions
  • Relationships with other feature layers and tables. Feature layers and tables can be related to one-another. For example, a feature layer containing trees could be related to a non-spatial table containing tree inspection data, and each tree could have a number of related inspections.

Other properties describe the data the feature layer or table provides access to, and how that data can be accessed and displayed. Properties include:

  • Field definitions. Each definition include the field name, display name, type, default value, any domain values, and whether the field is required.
  • Geometry type (feature layer only)
  • Default display field. Client APIs typically use this to provide default feedback when interacting with data in a map or scene.
  • Default visualization (feature layer only)

Feature layer/table URL

Each feature layer and table has an ID that uniquely identifies it within the feature service. To access a feature layer or table, append its ID to the service URL.

Use dark colors for code blocks
Ā 
1
https://<host>/<uniqueID>/ArcGIS/rest/services/<serviceName>/FeatureServer/<Layer or Table ID>

For example:

Use dark colors for code blocksCopy
Ā 
1
https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/arcgis/rest/services/Mobile_Data_Collection_WFL1/FeatureServer/0

Learn more about standard and enhanced endpoints in Service endpoints.

NameDescriptionExamples
fThe format of the data returned.f=json f=pjson f=geojson f=html
tokenAn API key or OAuth 2.0 access token. Learn how to get an access token in Security and authentication.token=<YOUR_API_KEY>
token=<ACCESS_TOKEN>

Code examples

View feature layer properties

Explore a feature layer by visiting its web page:

Get feature layer properties

Get the properties for the feature layer with ID 0 in this service as formatted JSON.

The service is shared with everyone, so no token is required.

Use dark colors for code blocksCopy
Ā 
1
https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/arcgis/rest/services/Mobile_Data_Collection_WFL1/FeatureServer/0?f=pjson

Query data

To access data in a feature service, you use the query operation on a feature layer or table:

Use dark colors for code blocks
Ā 
1
https://<host>/<uniqueID>/ArcGIS/rest/services/<serviceName>/FeatureServer/<Layer or Table ID>/query

Queries can include a SQL clause and/or a spatial query:

  • Use SQL to specify which records to return based on their attribute values. For example, counties with a specific tax rate code, or trees that are a specific species. Use the where parameter to specify a SQL clause.
  • Use a spatial query to specify which features to return based on the relationship of a query geometry to their geometries. Spatial queries are only supported by feature layers. For example, roads that cross a water main, or mailboxes within 1000ft of your location.
    • Use the geometry, geometryType, spatialRel, and inSR parameters to specify a query geometry.
    • Use geometry, geometryType, distance, and units to return features near a location.

You can combine a spatial query with a SQL clause. For example, trees of a specific type within 200m of your home.

You can control various aspects of the data that is returned by the query, such as:

  • Which attributes to return
  • Whether to return geometries for features
  • The detail included in returned geometries
  • The spatial reference of returned geometries

Frequently used parameters are described below.

Required parameters

f

The format of the query response:

  • json
  • pjson
  • geojson
  • html
  • pbf

ArcGIS client APIs use json (or pbf when displaying content in a map view or scene view). Many open source APIs use geojson.

To see which formats are supported for a particular feature layer, see the supportsQueryFormats property of the feature layer.

token

The access token used to access restricted operations or private content. The value can be an API Key or OAuth 2.0 token.

API keys are limited and do not provide access to restricted operations, but they can be used to access private content such as private feature layers, vector tile layers, image tile layers, web maps, and web scenes. API keys must be scoped to access specific content.

OAuth 2.0 tokens, however, can be used to access restricted operations and all private data types within the scope of the user's credentials.

Learn more about access tokens and authentication methods in Security and authentication.

SQL parameters

To query by attribute, you only need to provide a SQL clause.

where

The where parameter is a SQL clause that defines which data to return based upon attribute values. To query based upon geometry, see the geometry and spatialRel parameters.

Learn more about the SQL-92 format here.

Spatial parameters

These parameters are often used when performing a spatial query.

geometry

The geometry parameter is key to all spatial queries.

The query result will include features that relate to the geometry parameter value according to a spatial relationship specified by the spatialRel parameter.

geometry can be specified in one of 3 formats:

  • Simple point syntax: geometry=<x>,<y>
  • Simple envelope syntax: geometry=<xmin>,<ymin>,<xmax>,<ymax>
  • Full JSON syntax: geometry={...}

To use the geometry parameter, you must also provide a geometryType parameter. If you use the simple syntax for the geometry, you should also specify the inSR parameter.

geometryType

When a geometry parameter is provided, you must also specify the geometryType parameter. Valid values are:

  • esriGeometryPoint
  • esriGeometryMultipoint
  • esriGeometryPolyline
  • esriGeometryPolygon
  • esriGeometryEnvelope

spatialRel

spatialRel defines how the query geometry relates to features that should be returned in the query response.

Valid values are:

  • esriSpatialRelIntersects (default)
  • esriSpatialRelWithin
  • esriSpatialRelContains
  • esriSpatialRelCrosses
  • esriSpatialRelOverlaps
  • esriSpatialRelTouches
  • esriSpatialRelEnvelopeIntersects
  • esriSpatialRelIndexIntersects

For example, to query for all trees in a park, pass the park outline as the geometry and use spatialRel=esriSpatialRelContains.

The most common spatial relationships typically used in a query are esriSpatialRelIntersects, esriSpatialRelWithin, and esriSpatialRelContains.

Learn more about spatial relationships here.

inSR

This specifies the spatial reference of the geometry parameter. You can specify a WKID, or full spatial reference JSON.

Common WKIDs are 4326 for GPS data (inSR=4326), and 3857 for Web Mercator data.

To learn more, see Spatial references.

distance

Buffer the geometry parameter by an amount. The units of the amount are specified in the units parameter.

distance and units parameters are useful to search near a point. Set the geometry to a point, and specify the distance and units.

units

The units for the value provided in the distance parameter. Valid values are:

  • esriSRUnit_Meter
  • esriSRUnit_StatuteMile
  • esriSRUnit_Foot
  • esriSRUnit_Kilometer
  • esriSRUnit_NauticalMile
  • esriSRUnit_USNauticalMile

Output parameters

These parameters are used to define and optimize the query response.

outSR

The spatial reference to use for feature geometries returned in the query response.

You can specify a WKID, or full spatial reference JSON.

If features are being accessed to display in a map or scene, outSR typically matches the spatial reference of the map view or scene view. This avoids having to project features on the fly. Client APIs make use of outSR to improve performance of mapping applications.

A common WKID is 3857 (outSR=3857), which is the spatial reference used by most basemap layers.

To learn more, see Spatial references.

outFields

A list of field names that specifies the attributes to return with any records (for example, outFields=AREANAME,ST,POP2000).

The more fields you request, the larger the attributes portion of the response JSON payload and the longer it could take to download. Only request the fields you need for display or analysis.

To return all fields, which can be useful during development and testing, use outFields=*.

returnGeometry

Whether to return geometries with feature results.

Geometries are returned by default when querying a feature layer. If features will not be displayed in a map or scene, you can pass returnGeometry=false to exclude geometries from the query response.

For other methods that reduce the payload size of geometries returned in a query response, see maxAllowableOffset, geometryPrecision, and quantization parameters in the REST API documentation.

orderByFields

Order the records that are included in the response by specifying which fields to sort by and a sort order for each field:

  • ASC - ascending order (default)
  • DESC - descending

For example, orderByFields=STATE_NAME ASC, RACE DESC, GENDER.

Code examples

Get features with a SQL query

Get all trees in this feature layer listed as in the DOWNTOWN neighborhood and which have a DBH (diameter at breast height) of less than 2ft. Return geometries in longitude,latitude coordinates, and order the results by DBH. Only return the Address, Neighborhood, and DBH attributes.

Use dark colors for code blocksCopy
Ā 
1
https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/ArcGIS/rest/services/Mobile_Data_Collection_WFL1/FeatureServer/0/query?where=Neighborhood='DOWNTOWN'+AND+DBH+<+2&outFields=Address,Neighborhood,DBH&returnGeometry=true&outSR=4326&orderByFields=DBH&f=json

To get the results as GeoJSON, replace the f=json parameter above with f=geojson.

Use dark colors for code blocksCopy
Ā 
1
https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/ArcGIS/rest/services/Mobile_Data_Collection_WFL1/FeatureServer/0/query?where=Neighborhood='DOWNTOWN'+AND+DBH+<+2&outFields=Address,Neighborhood,DBH&returnGeometry=true&outSR=4326&orderByFields=DBH&f=geojson

Get features with a spatial query

Get all trees in this feature layer that are within 200m of 45.512 latitude, -122.686 longitude. Return coordinates as latitude and longitude.

Use dark colors for code blocksCopy
Ā 
1
https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/ArcGIS/rest/services/Mobile_Data_Collection_WFL1/FeatureServer/0/query?geometry=-122.686,45.512&geometryType=esriGeometryPoint&inSR=4326&distance=200&units=esriSRUnit_Meter&outFields=ADDRESS,Neighborhood,DBH&returnGeometry=true&outSR=4326&orderByFields=DBH&f=json

To get the results as GeoJSON, replace the f=json parameter above with f=geojson.

Use dark colors for code blocksCopy
Ā 
1
https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/ArcGIS/rest/services/Mobile_Data_Collection_WFL1/FeatureServer/0/query?geometry=-122.686,45.512&geometryType=esriGeometryPoint&inSR=4326&distance=200&units=esriSRUnit_Meter&outFields=ADDRESS,Neighborhood,DBH&returnGeometry=true&outSR=4326&orderByFields=DBH&f=geojson