Find
- URL:http:// <mapservice-url>/find
- Required Capability:Data
- Version Introduced:9.3
Description
The find operation is performed on a map service resource. The result of this operation is a find results resource. Each result includes its value, feature ID, field name, layer ID, layer name, geometry, geometry type, and attributes in the form of name-value pairs.
The find operation is not supported on stand-alone tables.
You can provide arguments to the find operaton as query parameters as defined in the parameters table below.
New in 10.1
- Support for dynamic layers was added with the dynamicLayers parameter. If dynamicLayers is used in a find operation request, layerDefs and layers (find) operation parameters are ignored. Instead, use definitionExpression available within dynamicLayers to specify these values in the find operation. Only those layers that are defined in dynamicLayers are used in the find operation.
- The gdbVersion parameter was introduced. Use this parameter to switch the geodatabase version of the map layers data source.
- The geometryPrecision parameter was introduced. This option can be used to specify the number of decimal places in the response geometries returned by the identify operation.
- JSON response contains an optional property exceededTransferLimit. This property will be true only if the number of records exceeds the maximum number configured by the server administrator.
New in 10.0
- Support for generalizing geometries returned by the find operation was added.
Request Parameters
Parameter |
Details |
---|---|
f |
Description: The response format. The default response format is html. Values: html | json |
searchText |
Description: (Required) The search string. This is the text that is searched across the layers and fields the user specifies. Example: searchText=Los |
contains |
Description: If false, the operation searches for an exact match of the searchText string. An exact match is case sensitive. Otherwise, it searches for a value that contains the searchText provided. This search is not case sensitive. The default is true. Values: true | false |
searchFields |
Description: The names of the fields to search. The fields are specified as a comma-separated list of field names. If this parameter is not specified, all fields are searched. Syntax: searchFields=<fieldName1>,<fieldName2> Where fieldName1, fieldName2 are the field names returned by the layer resource. Example: searchFields=AREANAME,SUB_REGION |
sr |
Description: The well-known ID of the spatial reference of the output geometries. If sr is not specified, the output geometries are returned in the spatial reference of the map. |
layerDefs |
New in 10.0. Description: Allows you to filter the features of individual layers in the exported map by specifying definition expressions for those layers. Definition expression for a layer that is published with the service will be always honored. Simple Syntax: Syntax: layerId1:layerDef1;layerId2:layerDef2 Where layerId1, layerId2 are the layer ids returned by the map service resource. Example: 0:POP2000 > 1000000;5:AREA > 100000 JSON Syntax: You can also use a JSON representation for Layer Definitions. Syntax: Where layerId1, layerId2 are the layer ids returned by the map service resource. |
layers |
Description: (Required) The layers to perform the find operation on. The layers are specified as a comma-separated list of layer ids. Syntax: layers=<layerId1>,<layerId2> Where layerId1 ,layerId2 are the layer ids returned by the map service resource. Example: layers=2,4,7 |
returnGeometry |
Description: If true, the resultset includes the geometries 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 maximum allowable offset to be used for generalizing geometries returned by the find operation. The maxAllowableOffset is in the units of the sr. If sr in not specified, the 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 find operation. This applies to X and Y values only (not m or z values). Example: geometryPrecision=3 |
dynamicLayers |
//This option was added at 10.1. Description: Use dynamicLayers property either to modify the data source of existing layers in the current map service or to add new layers. The new layer should have its source pointing to one of the registered workspaces that was defined at the time the map service was created. When defining a dynamic layer, source is required. Syntax:
Example:
|
returnZ |
//This option was added at 10.1. Description: If true, Z values will be included in the results if the features have Z values. Otherwise, Z values are not returned. The default is true. Note: This parameter only applies if returnGeometry=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. Note: This parameter only applies if returnGeometry=true. |
gdbVersion |
//This option was added at 10.1. Description: Switch map layers to point to an alternate geodabase version. Syntax: gdbVersion=<geodatabase version> Example: gdbVersion=sde.USER1 |
Example Usage
Example 1: Find operation that includes search text and a layer. The response is in HTML format:
Example 2: Find operation with dynamicLayer:
JSON Response Syntax
{"results" : [ { "layerId" : <layerId1>, "layerName" : "<layerName1>", "displayFieldName" : "<displayFieldName1>" "foundFieldName" : "<foundFieldName1>", "value" : "<value1>", "attributes" : { "<fieldName11>" : <fieldValue11>, "<fieldName12>" : <fieldValue12> }, "geometryType" : "<geometryType1>","hasZ" : <true|false>, //added in 10.1"hasM" : <true|false>, //added in 10.1 "geometry" : {<geometry1>} }, { "layerId" : <layerId2>, "layerName" : "<layerName2>", "displayFieldName" : "<displayFieldName2>" "foundFieldName" : "<foundFieldName2>", "value" : "<value2>", "attributes" : { "<fieldName21>" : <fieldValue21>, "<fieldName22>" : <fieldValue22> }, "geometryType" : "<geometryType2>","hasZ" : <true|false>, //added in 10.1"hasM" : <true|false>, //added in 10.1 "geometry" : {<geometry2>} }]}
JSON Response Example
{"results" : [ { "layerId" : 3, "layerName" : "Cities", "displayFieldName" : "City Name" "foundFieldName" : "City Name", "value" : "Joe City", "attributes" : { "City Name" : "Joe City", "CLASS" : "city", "ST" : "CA" }, "geometryType" : "esriGeometryPoint", "geometry" : { "x" : -118.375, "y" : 34.086, "spatialReference" : {"wkid" : 4326} } }, { "layerId" : 59, "layerName" : "Parcel", "displayFieldName" : "NAME" "foundFieldName" : "NAME", "value" : "Joe's Parcel", "attributes" : { "NAME" : "Parcel 649", "SUB_REGION" : "Pacific", "STATE_ABBR" : "CA" }, "geometryType" : "esriGeometryPolygon", "geometry" : { "spatialReference" : {"wkid" : 4326}, "rings" : [[[-118.35,32.81],[-118.42.806],[-118.511,32.892],[-118.35,32.81]]]} }]}