Render Legend for a Map
Description
Returns the complete legend of a map specifying the map definition as JSON, the swatch size, and mime type of the legends. The legend is returned as single swatch rows, including a Base64-encoded image (or URL) and text description, that make up a complete legend. For each layer in the map definition, zero, one, or more legend entries will be returned.
When inLineSwatch is passed as false, the map definition's JSON is used to create a unique key. This key, along with the path(legends/{legendIndex}/rows/{rowindex}), is put into the cache. This key can be used in the getSwatch operation to retrieve the legend from the cache.
The body JSON representation is in GeoJSON format. For more information on GeoJSON, see geojson.org/geojson-spec.html.
ACL Authorization Flow
To return the complete legend of a map, the user (or the role they belong to) needs EXECUTE permission on the Named table.
HTTP POST URL Format
The following format is used for HTTP POST requests:
HTTP POST: /maps/legends.json;
POST DATA: w=width;h=height;t=image type;
[r=resolution]?[inlineSwatch=boolean]&[ignoreLegendRowOverrideVisibility=boolean]
POST BODY: Content-Type:application/json {map definition, containing an object of a Map, layer array, or FeatureCollection}
Parameters
For information on the parameter types listed below, see Request URL Data Types.
Parameter | Type | Required | Description |
---|---|---|---|
type | String | yes | The type of information to return the legend (e.g., JSON) |
w=width | Integer | yes | Width of the individual legend swatch in pixels |
h=height | Integer | yes | Height of the individual legend swatch in pixels |
t=image type | String | yes | The type of images to return for the legend swatches (e.g., gif, png, etc.) |
r=resolution | Integer | no | The DPI resolution of the legend swatches as an integer. DPI measures the resolution of images in dots per inch (the number of individual dots that can be placed within the span of one linear inch). If not specified then assumes server default. |
inlineSwatch=boolean | Boolean | no | Determines if the swatch images are returned as data or URL to the image location on the server. By default all swatch images are returned as Base64-encoded images in the JSON response (inlineSwatch=true). To return swatch image URLs to the images located on the server, specify inlineSwatch=false. |
ignoreLegendRowOverrideVisibility=boolean | Boolean | no | Ignores the LegendRowOverride visibility setting in a named resource and returns all legends. |
Example
Return the legend (swatches and information) for the MapWithLayer map, located in the /Samples/NamedMaps directory in the repository, in JSON format. The swatches will be 32 x 16, in PNG format, and returned as Base64-encoded images. The map is defined using a single layer defined in the JSON body.
http://hostname:port/rest/Spatial/MappingService/maps/legends.json;w=16;h=32;t=png
Content-type: application/json
Authorization: <Basic or Spectrum Token>
{
'layers':[
{
'type':'NamedLayer',
'name':'/Samples/NamedLayers/UK_REGNS_Layer'
}
]
}
The body of the request can contain either a layer array (as above), Map or Featurecollection. The following are examples of Map and FeatureCollection objects:
{
"MapDescription": {
"version": "1.0",
"name": "Samples/NamedMaps/WorldMap",
"layers":[
{
"type":"NamedLayer",
"name":"/Samples/NamedLayers/USALayer"
}
]
}
}
{ "type": "FeatureCollection",
"features": [
{ "type": "Feature",
"geometry": {"type": "Point", "coordinates": [102.0, 0.5]},
"properties": {"prop0": "value0"}
},
{ "type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]
]
},
"properties": {
"prop0": "value0",
"prop1": 0.0
}
},
{ "type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0],
[100.0, 1.0], [100.0, 0.0] ]
]
},
"properties": {
"prop0": "value0",
"prop1": {"this": "that"}
}
}
]
}
Returns
Returns an array of string values returned in a JSON response object that represent all the legend swatches for a map. For each layer in the map, zero, one, or more legend entries will be returned.
In the following response, inlineSwatch is true. The image is returned as the default Base64-encoded image.
{
"LegendResponse":[{"layerName":"UK REGNS",
"rows":[{
"description":"Region","swatch":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAAy
CAYAAAAeP4ixAAAASUlEQVR42u3PQRUAAAREQf3TacRBCszu+wEm4tjqQAPJxQcBAQEBAQEBAQEBAQEBAQEB
AQEBAQEBAQEBAQEBAQEBAQEBeQHZXgPRVfdw38uLQQAAAABJRU5ErkJggg=="
}],
"title":"UK REGNS",
"type":"CARTOGRAPHIC"}]
}
The following response is the same swatch as above; however, a URL to the generated swatch image is returned (setting the inlineSwatch parameter to false).
{
"LegendResponse":[{"layerName":"UK REGNS",
rows":[{
"description":"Region","swatch":"http://<hostname>:<port>/rest/Spatial/MappingService/maps/
ae16d6e47ab63e2a840f8b1f205e12bb/legends/0/rows/0/swatch/50x50.png"}],
"title":"UK REGNS","type":"CARTOGRAPHIC"}]
}