Query Legends

URL:
https://<mapservice-url>/queryLegends
Methods:
GET
Version Introduced:
10.7.1

Description

As of 10.7.1, you can perform this operation on a map service to return information about the map service's legend by layer. As opposed to the Legend resource, which provides a complete representation of the map legend, this operation allows you to filter the results by specifying parameters.

Each layer's legend information includes the symbol images and labels for each symbol. You can specify an image size for the symbol images. They include the base64-encoded imageData , as well as a URL that can be used to retrieve the image from the server site.

Additional information for each layer, such as the layer ID, name, and scale, is also included.

Most of the available request parameters are also found in the Export Map operation.

New at 10.9

Supports the following new parameters. These parameters are only supported by map services published from ArcGIS Pro.

  • timeRelation to control whether you want to include or exclude start and end values specified in the time parameter.

New at 10.8

Supports the following new parameters. These parameters are only supported by map services published from ArcGIS Pro.

  • clipping to mask out layers outside of a clip polygon.
  • spatialFilter to draw or query only features that meet the spatial filter criteria.

Request parameters

ParameterDetails

returnVisibleOnly

(Return Visible Only)

If set to true , as by default, a legend item class will only appear in the legend if a feature from that item class is included in the current extent. If set to false , all items in the legend will be included in the operation results. This is the same result as when using the static Legend resource. Because that resource is static, it performs faster than this operation; it's better to use the Legend resource if you want to obtain all legend items.

Values: true | false

bbox

(Bounding Box)

(Required)

Specifies the extent (bounding box) of the exported image. Unless the bboxSR parameter has been specified, the bbox is assumed to be in the spatial reference of the map. The bbox coordinates should always use a period as the decimal separator, even in countries where traditionally a comma is used.

Syntax

Use dark colors for code blocksCopy
1
<xmin>, <ymin>, <xmax>, <ymax>

Example

Use dark colors for code blocksCopy
1
bbox=-104,35.6,-94.32,41

bboxSR

(Bounding Box Spatial Reference)

Specifies the spatial reference of the bbox . The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object. If the bboxSR parameter is not specified, the bbox parameter is assumed to be in the spatial reference of the map.

layers

(Layers)

Determines which layers appear on the exported map. There are four ways to specify which layers are shown:

  • show —Only the layers specified in this list will be exported.
  • hide —All layers except those specified in this list will be exported.
  • include —In addition to the layers exported by default, the layers specified in this list will be exported.
  • exclude —The layers exported by default, excluding those specified in this list, will be exported.

Syntax

Use dark colors for code blocksCopy
1
2
//Where layerId1 and layerId2 are the layer IDs returned by the
[show | hide | include | exclude]:layerId1,layerId2

Example

Use dark colors for code blocksCopy
1
layers=show:2,4,7

layerDefs

(Layer Definitions)

Allows you to filter the features of individual layers in the exported map by specifying definition expressions for those layers. Definition expressions for a layer that is published with the service will always be honored.

Syntax

Use dark colors for code blocksCopy
1
2
//Where layerId1 and layerId2 are the layer IDs returned by the map service resource.
{"<layerId1>": "<layerDef1>", "<layerId2>": "<layerDef2>"}

size

(Image Size)

Specifies the size (width and height) of the exported image in pixels. If the size parameter is not specified, an image with a default size of 400 by 400 pixels will be exported.

Syntax

Use dark colors for code blocksCopy
1
<width>, <height>

Example

Use dark colors for code blocksCopy
1
size=600,550

imageSR

(Image Spatial Reference)

Specifies the spatial reference of the exported image. The spatial reference can be specified as either a well-known ID or as a spatial reference json object. If the imageSR parameter is not specified, the image will be exported in the spatial reference of the map.

historicMoment

(Historic Moment)

Returns an output image with features from a specific epoch time. This parameter applies only if the layer is archiving enabled and the supportsQueryWithHistoricMoment property is set to true . This property is provided in the layer resource. If historicMoment is not specified, the current features are drawn.

Syntax

Use dark colors for code blocksCopy
1
historicMoment=<Epoch time in milliseconds>

Example

Use dark colors for code blocksCopy
1
historicMoment=1199145600000

format

(Image Format)

Specifies the format of the exported image. The default format is png .

Values: png | png8 | png24 | jpg | pdf | bmp | gif | svg | svgz | emf | ps | png32

transparent

(Background Transparent)

If set to true , the image will be exported with the background color of the map set as its transparent color. The default is false . Only the png and gif formats support transparency. Internet Explorer 6 does not display transparency correctly for png24 image formats.

Values: true | false

dpi

(DPI)

Specifies the device resolution of the exported image (dots per inch). If the dpi parameter is not specified, an image with a default DPI of 96 will be exported.

Example

Use dark colors for code blocksCopy
1
dpi=200

time

(Time)

Specifies the time instant or time extent of the exported map image.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
//Time instant syntax
time=<timeInstant>

//Time extent syntax
time=<startTime>, <endTime>

Example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//Time instant example (1 Jan 2008 00:00:00 GMT)
time=1199145600000

//Time extent example (1 Jan 2008 00:00:00 GMT to 1 Jan 2009 00:00:00 GMT)
time=1199145600000, 1230768000000

//A null value specified for start time or end tie will represent infinity for start or end time, respectively
time=null,1230768000000

timeRelation

(Time Relation)

Allows you to control whether to include or exclude features that are at the beginning or the end of a time window. The default value is esriTimeRelationOverlaps .

Values: esriTimeRelationOverlaps | esriTimeRelationOverlapsStartWithinEnd | esriTimeRelationAfterStartOverlapsEnd | esriTimeRelationWithin

Examples, used with the time parameter

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
//Draw all features from year 2008 i.e. Jan 1st, 2008 00:00:00 GMT to Jan 1st 2009 00:00:00 GMT including Jan 1st, 2009 00:00:00 GMT
time=1199145600000,1230768000000&timeRelation=esriTimeRelationOverlaps

//Draw all features from year 2008 i.e. Jan 1st, 2008 00:00:00 GMT to Jan 1st 2009 00:00:00 GMT excluding Jan 1st, 2009 00:00:00 GMT
time=1199145600000,1230768000000&timeRelation=esriTimeRelationOverlapsStartWithinEnd

//Draw all features from Jan 1st, 2008 00:00:00 GMT to Jan 1st 2009 00:00:00 GMT excluding Jan 1st, 2008 00:00:00 GMT
time=1199145600000,1230768000000&timeRelation=esriTimeRelationAfterStartOverlapsEnd

//Draw all features after Jan 1st, 2008 00:00:00 GMT and before Jan 1st 2009 00:00:00 GMT
time=1199145600000,1230768000000&timeRelation=esriTimeRelationWithin

layerTimeOptions

(Layer Time Options)

Specifies the time options per layer. Users can indicate whether the layer should use the time extent specified by the time parameter, whether to draw the layer features cumulatively, and the time offsets for the layer.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "<layerId1>": {
    "useTime": < true | false >,  //If true, use the time extent specified by the time parameter
    "timeDataCumulative": < true | false >,  //If true, draw all the features from the beginning of time for that data
    "timeOffset": <timeOffset1>,  //Time offset for this layer so that it can be overlaid on the top of a previous or future time period
    "timeOffsetUnits": "<esriTimeUnitsCenturies | esriTimeUnitsDays | esriTimeUnitsDecades |
                       esriTimeUnitsHours | esriTimeUnitsMilliseconds | esriTimeUnitsMinutes |
                       esriTimeUnitsMonths | esriTimeUnitsSeconds | esriTimeUnitsWeeks | esriTimeUnitsYears |
                       esriTimeUnitsUnknown>"
  },
  "<layerId2>": {
    "useTime": < true | false >,
    "timeDataCumulative": < true | false >,
    "timeOffsetOffset": <timeOffset2>,
    "timeOffsetUnits": "<timeOffsetUnits2>"
  }
}

Example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
{
  "0": {
    "useTime": true,
    "timeDataCumulative": false,
    "timeOffset": 1,
    "timeOffsetUnits": "esriTimeUnitsYears"
  },
  "3": {
    "useTime": false
  }
}

dynamicLayers

(Dynamic Layers)

Modifies the layer drawing order, change layer drawing information, and change the layer data source version for this request. New layers (dataLayer ) can also be added to the dynamicLayers based on the map service registered workspaces. The order of the dynamicLayers array defines the layer drawing order. The first element of the dynamicLayers array draws on top of all other layers. Keep the following in mind when using this parameter:

  • When defining a dynamic layer, if the layer source is of type mapLayer, use the ID in layer resource as the mapLayerId for the dynamic layer.
  • If the layer source is a dataLayer based on a data table (table or queryTable dataSource), set drawingInfo .
  • If the layer source is a workspace layer based on a layer file (.lyrx ) generated from ArcGIS Pro, drawingInfo is optional. When drawingInfo is provided, map service ignores the symbology that is stored with the layer file and instead uses the one the user provides.
  • transparency is on a scale of 1 to 100, where 0 is opaque and 100 is 100 percent transparent.
  • Use scaleSymbols to turn off scaling symbols on a layer that reports canScaleSymbols to be true on the layer resource.
  • Use showLabels to turn on or turn off labeling on a layer that has labels (hasLabels set to true on the layer resource).
  • To turn on labels on a layer that does not have labels defined on it, set showLabels to true and use labelingInfo to specify labels.
  • Dynamic layers support both the Standard Label Engine and the Maplex Label Engine. The labeling engine used is dependent on the one that was set in the map document used to create the map service.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
[
  {
    "id": <layerOrTableId>,
    "source": <layer source>,
    "definitionExpression": "<definitionExpression>",
    "drawingInfo": {
      "renderer": <renderer>,
      "transparency": <transparency>,
      "scaleSymbols": <true | false >,
      "showLabels": <true | false >,
      "labelingInfo": <labeling info>
    },
    "layerTimeOptions": {
      "useTime": <true | false>,
      "timeDataCumulative": <true | false>,
      "timeOffset": <timeOffset>,
      "timeOffsetUnits": "<esriTimeUnitsCenturies | esriTimeUnitsDays | esriTimeUnitsDecades |
                         esriTimeUnitsHours | esriTimeUnitsMilliseconds | esriTimeUnitsMinutes |
                         esriTimeUnitsMonths | esriTimeUnitsSeconds | esriTimeUnitsWeeks | esriTimeUnitsYears |
                         esriTimeUnitsUnknown>"
    }
  },
  {
    "id": <layerOrTableId>,
    "source": <layer source>,
    "definitionExpression": "<definitionExpression>",
    "drawingInfo": {
      "renderer": <renderer>,
      "transparency": <transparency>,
      "scaleSymbols": <true | false >,
      "showLabels": <true | false >,
      "labelingInfo": <labeling info>
    },
    "layerTimeOptions": {
      "useTime": <true | false>,
      "timeDataCumulative": <true | false>,
      "timeOffset": <timeOffset>,
      "timeOffsetUnits": "<esriTimeUnitsCenturies | esriTimeUnitsDays | esriTimeUnitsDecades |
                         esriTimeUnitsHours | esriTimeUnitsMilliseconds | esriTimeUnitsMinutes |
                         esriTimeUnitsMonths | esriTimeUnitsSeconds | esriTimeUnitsWeeks | esriTimeUnitsYears |
                         esriTimeUnitsUnknown>"
    }
  }
]

See the Dynamic Layers code block examples section below for examples.

gdbVersion

(Geodatabase Version Name)

Specifies the geodatabase version.

Example

Use dark colors for code blocksCopy
1
gdbVersion=<geodatabase version>

Example

Use dark colors for code blocksCopy
1
gdbVersion=sde.USER1

mapScale

(Map Scale)

Exports a map image at a specific scale, with the map centered at the center of the specified bounding box (bbox ). Where scale is typically represented as 1:x , this value is x .

Syntax

Use dark colors for code blocksCopy
1
mapScale=<scale>

Examples

Use dark colors for code blocksCopy
1
2
3
mapScale=5000000

mapScale=5E6

rotation

(Rotation)

Exports a map image rotated at a specific angle, with the map centered at the center of the specified bounding box (bbox ). It could be a positive or negative number.

Syntax

Use dark colors for code blocksCopy
1
rotation=<degree>

Examples

Use dark colors for code blocksCopy
1
2
//returns a map image rotated 45 degrees counterclockwise
rotation=45

datumTransformations

(Datum Transformations)

Applies one or more datum transformations to the map when imageSR 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 imageSR .

For a list of valid datum transformation ID values and well-known ID (WKID) text strings, see Using spatial references. For more information on datum transformation, see the transformation parameter in the Project operation.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
//Syntax with WKID
datumTransformations=[wkid1, wkid2]

//Syntax with datum
datumTransformations=[{<dt1>}, {<dt2>}]

Examples

Use dark colors for code blocksCopy
1
2
3
4
5
//Examples with WKID to apply multiple transformations
datumTransformations=[1623, 4078]

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

layerParameterValues

(Layer Parameter Values)

Filters the features of individual layers in the exported map by specifying values to an array of preauthored parameterized filters for those layers. When this value is not specified for any parameter in a request, the default value assigned during authoring is used instead. When a parameterInfo parameter allows multiple values, you must pass them in an array.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
[
  {
    "<layerId1>": {
      "<parameterName1>": <value>,               //when the multipleValues=false in the parameterInfo
      "<parameterName2>": [<value1> | <value2>]  //when the multipleValues=true in the parameterInfo
    },
    "<layerId2>": {
      "<parameterName3>": <value>
    }
  }
]
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
[
  {
    "0": {
      "floor": 10,
      "incidentDate": 1475877014000    //date time value needs to be passed in as epoch value
    },
    "1": {
      "crimeType": ["burglary", "theft"]
    }
  }
]

mapRangeValues

(Map Range Values)

Filters features in the exported map from all layers that are within the specified range instant or extent.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
[
  {
    "name": "<rangeName1>",           //range id
    "value": <value> | [ <value1>, <value2> ] //single value or 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> ] //single value or value-range
  }
]

Example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
[
  {
    "name": "salinity",
    "value": 5  //a range instant (or single) value passed

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

layerRangeValues

(Layer Range Values)

Filters the features of individual layers in the exported map by specifying values to an array of preauthored parameterized filters for those layers. When this value is not specified for any parameter in a request, the default value assigned during authoring is used instead. When a parameterInfo parameter allows multiple values, you must pass them in an array.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
[
  {
    "<layerId1>" : {
      "<parameterName1>": <value>,               //when the multipleValues=false in the parameterInfo
      "<parameterName2>": [<value1> | <value2>]  //when the multipleValues=true in the parameterInfo
    },
    "<layerId2>": {
      "<parameterName3>": <value>
    }
  }
]

Example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
[
  {
    "0": {
      "floor": 10,
      "incidentDate": 1475877014000    //date time value needs to be passed in as epoch value
    },
    "1": {
      "crimeType": ["burglary", "theft"]
    }
  }
]

patchSize

(Patch Size)

Specifies the dimensions of the exported image for each symbol in the legend. This is specified in device-independent units of points (1 inch = 72 points). If this parameter is not specified, the default size of 15 by 15 points (20 by 20 pixels at 96 dpi) will be exported. Note that this property has no effect on the point or marker legend patches, as those depend on the actual marker size in the legend.

Syntax

Use dark colors for code blocksCopy
1
<width>, <height>

clipping

(Clipping)

Added at 10.8. Masks out layers outside of the clip polygon in the exported map. Clipping can mask out any layer type, in other words, feature layers, raster layers, TIN layers, and so on. Optionally, you can use excludedLayers to exclude layers from being clipped.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
{
  "geometryType": "<esriGeometryPolygon | esriGeometryEnvelope>",
  "geometry": {<geometry>},
  "excludedLayers": [<layerId>, <layerId>] //optional
}

Example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "geometryType": "esriGeometryPolygon",
  "geometry": {
    "spatialReference": {
      "wkid": 102008
    },
    "rings": [
      [
        [-816126, 216280],
        [-565859, 199948],
        [-607349, -50318],
        [-785229, -38842],
        [-816126, 216280]
      ]
    ]
  },
  "excludedLayers" : [ 1, 4 ] //optional
}

spatialFilter

(Spatial Filter)

Added at 10.8. Filters out features from all feature layers based on the input spatial filter. This parameter is similar to layerDefs but instead of using an attribute filter, the map service uses spatialFilter to determine which features can be queried.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
{
  "spatialRel": "<esriSpatialRelIntersects | esriSpatialRelContains | esriSpatialRelCrosses | esriSpatialRelEnvelopeIntersects
                | esriSpatialRelIndexIntersects | esriSpatialRelOverlaps | esriSpatialRelTouches
                | esriSpatialRelWithin | esriSpatialRelRelation>", //default = esriSpatialRelIntersects
  "geometryType": "<esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope >",
  "geometry": { <geometry> }
}

Example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "spatialRel": "esriSpatialRelIntersects",
  "geometryType": "esriGeometryPolygon",
  "geometry": {
    "spatialReference": {
      "wkid": 102008
    },
    "rings": [
      [
        [-816126, 216280],
        [-565859, 199948],
        [-607349, -50318],
        [-785229, -38842],
        [-816126, 216280]
      ]
    ]
  }
}

f

(Format)

The response format. Only json can be specified for this value.

Response properties

PropertyDetails

layerId

The unique order ID number for the layer, as given in the map service resource.

layerName

The name of the layer.

minScale

The minimum scale extent for the layer. Where scale is typically expressed as 1:x , this value is x .

maxScale

The maximum scale extent for the layer.

legend

Provides a representation of each entry in the legend. The following properties are given for each entry:

  • label
  • url
  • imageData
  • contentType
  • height
  • width
  • values

JSON Response syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
{
  "layers": [
    {
      "layerId": <layerId1>,
      "layerName": "<layerName1>",
      "layerType" : "<layerType1>",
      "minScale": <minScale1>,
      "maxScale": <maxScale1>,
      "legend": [
        {
          "label": "<label11>",
          "url" : "<imageUrl11>", //Relative URL for static layers and full URL for dynamic layers. Access relative URL using https://<mapservice-url>/<layerId1>/images/<imageUrl11>
          "imageData" : "<base64EncodedImageData11>",
          "contentType" : "<contentType11>",
          "height": <height>,
          "width": <width>,
          "values": [<maximum value1>] //In case of classBreaks renderer values will contain classMaxValue
        },
        {
          "label": "<label12>",
          "url" : "<imageUrl12>",
          "imageData" : "<base64EncodedImageData12>",
          "contentType" : "<contentType12>",
          "height": <height>,
          "width": <width>,
          "values": [<maximum value2>]
        }
      ]
    },
    {
      "layerId": <layerId2>,
      "layerName": "<layerName2>",
      "layerType" : "<layerType2>",
      "minScale": <minScale2>,
      "maxScale": <maxScale2>,
      "legend": [
        {
          "label": "<label21>",
          "url" : "<imageUrl21>", //Relative URL for static layers and full URL for dynamic layers. Access relative URL using https://<mapservice-url>/<layerId2>/images/<imageUrl21>
          "imageData" : "<base64EncodedImageData21>",
          "contentType" : "<contentType21>",
          "height": <height>,
          "width": <width>,
          "values": ["uniqueValue1"] //In case of uniqueValue renderer values, this will contain ungrouped unique values.
        },
        {
          "label": "<label22>",
          "url" : "<imageUrl22>",
          "imageData" : "<base64EncodedImageData22>",
          "contentType" : "<contentType22>",
          "height": <height>,
          "width": <width>,
          "values": ["uniqueValue2", "uniqueValue3"]
        }
      ]
    }
  ]
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.