Find

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.

NoteNote:

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

New in 10.1

New in 10.0

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.

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"}

NoteNote:

Simple syntax is no longer supported starting 10.5.

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:

[
  {
    "id": <layerOrTableId>,
    "source": <layer source>,
    "definitionExpression": "<definitionExpression>"
  },
  {
    "id": <layerOrTableId>,
    "source": <layer source>,
    "definitionExpression": "<definitionExpression>"
  }
]

Example:

[
  {
    "id": 501,
    "source":
    {
      "type": "mapLayer",
      "mapLayerId": 0
    }
  },
  //add a new layer from registered workspace
  {
    "id": 502,
    "source":
    {
      "type": "dataLayer",
      "dataSource":
      {
        "type": "table",
        "workspaceId": "MAP",
        "dataSourceName": "MAP.user1.Taxlots"
      }
    }
  },
  //change the Version of existing map service layer
  {
    "id": 503,
    "source":
    {
      "type": "mapLayer",
      "mapLayerId": 1,
      "version": "USER1"
    },
    "definitionExpression": "neighborhood = 'French Quarter'"
  }
]
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.

NoteNote:

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.

NoteNote:

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

returnUnformattedValues

//This option was added at 10.5.

Description: If true, the values in the result will not be formatted i.e. numbers will returned as is and dates will be returned as epoch values.

NoteNote:

The default value is false i.e. numbers and dates are formatted based on server's setting.

Subtype and domain values will be returned as numeric values instead of descriptions.

returnFieldName

//This option was added at 10.5.

Description: If true, field names will be returned instead of field aliases.

NoteNote:

The default value is false.

In case with layers with joins, fully qualified field names will be returned.

datumTransformations

//This option was added at 10.5

Description: Use this parameter to apply one or more datum transformations to the map when sr is different than the map service's spatial reference. It is an array of transformation elements.

Transformations specified here are used to project features from layers within a map service to sr.

Note: while specifying transformation, you need to think about which datum transformation best applicable to project a layer(s) (not the map service) to the sr. sourceSpatialReference property in a layer resource reports which spatial reference features are stored in the source dataset.

For a list of valid datum transformation ID values and well-known text strings, see Geographic transformations.

Syntax: datumTransformations=[wkid1, wkid2].

Examples: datumTransformations=[1623, 4078] to apply multiple transformations.

Syntax: datumTransformations=[{<dt1>}, {<dt2>}].

Examples: datumTransformations=[{"wkid":108889}, {"geoTransforms":[{"wkid":108889,"transformForward":true},{"wkid":1622,"transformForward":false}]}] to apply multiple transformations including a composite transformation.

For more information on datum transformation, please see transformation parameter in Project operation.

mapRangeValues

//This option was added at 10.5

Description: Allows you to filter features in the exported map from all layer that are within the specified range instant or extent.

Note: Check rangeInfos at the layer resources for the available ranges.

Syntax:

[
  {
    "name" : "<rangeName1>",           //range id
    "value"   : <value> |               //single value or 
                [ <value1>, <value2> ] //a value-range 
                     // null is allowed in value-range case -- that means infinity
                     // e.g. [null, 1500] means all features with values <= 1500
                     // [1000, null] means all features with values >= 1000

  },
  {
    "name" : "<rangeName2>",
    "value" : <value> |  [ <value3>, <value4> ]
  }
]&

Example:

[{
  "name" : "salinity",
  "value" : 5            //a range instant (or single) value passed

 }, {
  "name" : "elevation",
  "value" : [1000, 1500] //a range extent is passed

}]
layerRangeValues

//This option was added at 10.5

Description: Allows you to filter features for each individual layer that are within the specified range instant or extent.

Note: Check rangeInfos at the layer resources for the available ranges.

Syntax:

{
  "<layerId1>" : [
    {
      "name" : "<rangeName1>",           //range id
      "value"   : <value> |               //single value or 
                  [ <value1>, <value2> ] //a value-range 
                       // null is allowed in value-range case -- that means infinity
                       // e.g. [null, 1500] means all features with values <= 1500
                       // [1000, null] means all features with values >= 1000

    },
    {
      "name" : "<rangeName2>",
      "value" : <value> |  [ <value3>, <value4> ]
    }
  ],
  "<layerId2>" : [
    {
      "name" : "<rangeName1>",
      "value"   : <value> | [ <value1>, <value2> ]

    }
  ]
}&

Example:

{
  "0" : [
    {
      "name" : "salinity",
      "value" : 5            //a range instant (or single) value passed
    },
    {
      "name" : "elevation",
      "value" : [1000, 1500] //a range extent is passed
    }
  ],
  "1" : [
    {
      "name" : "floor",
      "value" : [null, 5]   //selects features with values <= 5
    }
  ]
}
layerParameterValues

//This option was added at 10.5

Description: Allows you to filter the features of individual layers in the exported map by specifying value(s) to an array of pre-authored parameterized filters for those layers. When value is not specified for any parameter in a request, the default value, that is assigned during authoring time, gets used instead.

When a parameterInfo allows multiple values, you must pass them in an array.

Note: Check parameterInfos at the layer resources for the available parameterized filters, their default values and expected data type.

Syntax:

[
   {
     "<layerId1>" : {
       "<parameterName1>" : <value>,               //when the multipleValues=false in the parameterInfo
       "<parameterName2"> : [<value1> | <value2>]  //when the multipleValues=true in the parameterInfo
     },
     "<layerId2>" : {
       "<parameterName3>" : <value>
    }
  }
]&

Example:

[
   {
     "0" : {
       "floor" : 10,
       "incidentDate" : 1475877014000    //date time value needs to be passed in as epoch value
     },
     "1" : {
       "crimeType" : ["burglary", "theft"]
    }
  }
]&

Example Usage

Example 1: Find operation that includes search text and a layer. The response is in HTML format:

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/find?searchText=island&contains=true&searchFields=&sr=&layers=0,2&returnGeometry=true

Example 2: Find operation with dynamicLayer:

http://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/find?searchText=Calif&contains=true&searchFields=&sr=&layers=&layerDefs=&returnGeometry=false&maxAllowableOffset=&geometryPrecision=&dynamicLayers=[{"id":501,"source":{"type":"mapLayer","mapLayerId":3}}]&returnZ=false&returnM=false&gdbVersion=&f=html

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]]]} }]}