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.

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];[l=locale]?[inlineSwatch=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.
l=locale String no The locale in which to render the legend. Uses the Java Locale format consisting of an ISO two letter language code and an ISO two letter country code. 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.

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