Skip To Content

Filtering features using the layerDefs parameter in WMS requests

The WMS specification lacks a filtering mechanism in which you can append a query string or where clause in a GetMap request. Although the filters can be applied using the rules in the SLD, you will have to re-create the symbologies part in the SLD at the same time.

Alternatively, ArcGIS Server implements a vendor-specific parameter called layerDefs for both GetMap and GetFeatureInfo WMS operations. This provides a more lightweight way for the client to filter the features of individual layers in the exported map by specifying definition expressions for those layers.

The layerDefs parameter is derived from the ArcGIS Server map service layerDefs parameter. For more information about this parameter, see the ArcGIS REST API documentation.

Using layerDefs in a request

The following are some examples of how to use the layerDefs parameter in GetMap and GetFeatureInfo requests.


Keep in mind that filter expressions in the layerDefs parameter are mutually exclusive of those defined in the SLD and/or SLD_BODY. When both are present in a GetMap or GetFeatureInfo request, layerDefs has a lower priority and will be ignored.


Filter the country layer by displaying only those countries that have a population greater than 1 million: layerDefs={"country":"POP_CNTRY>100000000"}.

Sample request:,-90,180,83.604158999999996&WIDTH=660&HEIGHT=318&LAYERS=country&STYLES=default&EXCEPTIONS=xml&FORMAT=image/png&BGCOLOR=0xFEFFFF&TRANSPARENT=TRUE&layerDefs={"country":"POP_CNTRY>100000000"}


Filter the country layer by only obtaining information for countries that have a population greater than 1 million and contain a river named Amazon: layerDefs={"country":"POP_CNTRY>100000000","rivers":"NAME LIKE 'Amazon'"}.

Sample request:,-90,180,83.604158999999996&WIDTH=660&HEIGHT=318&LAYERS=country,rivers&STYLES=default,default&EXCEPTIONS=xml&FORMAT=image/png&BGCOLOR=0xFEFFFF&TRANSPARENT=TRUE&QUERY_LAYERS=country,rivers&INFO_FORMAT=text/html&I=50&J=50&layerDefs={"country":"POP_CNTRY>100000000","rivers":"NAME LIKE 'Amazon'"}

Filtering images in WMS requests

A WMS based on an image service supports image filtering using vendor-specific parameters. Users can either specify a condition through the Query parameter, or image IDs through the Images parameter. The parameters apply to services published from mosaic datasets.


The IMAGES parameter queries individual rasters by their object IDs in the mosaic dataset.

Request: Displays one image whose object ID is 1:,-161.000416666667,23.0004166666666,-153.999583333333&WIDTH=981&HEIGHT=826&images=1

Request: Displays two images whose object IDs are 3 and 5:,-161.000416666667,23.0004166666666,-153.999583333333&WIDTH=981&HEIGHT=826&images=3,5


At 10.3, Image service WMS supports a new Query parameter. The Query parameter queries images based on a condition.

Request: Displays images whose project name starts with "Cotton". In the example, projectName is a custom field name in the mosaic dataset:,-.00056041068726637587,.0038293544476327114,.0040723426808816961&WIDTH=697&HEIGHT=817&LAYERS=0&STYLES=&FORMAT=image/png&BGCOLOR=0xFEFFFF&TRANSPARENT=TRUE&Query=ProjectName like 'Cotton%25'


The Query parameter only takes Standardized Queries by default. For more information, see About standardized queries.