GetMap

A GetMap request retrieves a map from a WMS site. GetMap allows the client to specify distinct layers, the spatial reference system, the geographic area, and other parameters describing the returned map format. Upon receiving the GetMap request, a WMS site will either satisfy the request or send an error message in accordance with the exception instructions contained in the GetMap request.

The following parameters can be appended to the GetMap request to control how the returned map looks. See the WMS Specification documentation for detailed descriptions of each parameter:

Request Parameter Required/Optional Description
REQUEST=GetMap R Request name.
VERSION=version R Request version. Valid values are 1.0.0, 1.1.0, or 1.1.1.
LAYERS=layer_list R Comma-separated list of one or more map layers. Values in list correspond to the layer <Name> values in the Capabilities file. Optional if SLD parameter is present in request.
SRS=EPSG:id_code R Spatial Reference System (SRS) identifier the map is returned in. Identifiers correspond to coordinate system ID codes found in the ArcXML Programmer’s Reference Guide.
BBOX=minx,miny,maxx,maxy R Bounding box corners (lower left, upper right). Values must be in units of the specified SRS.
WIDTH=output_width R Width in pixels of resulting map image.
HEIGHT=output_height R Height in pixels of resulting map image.
STYLES=style_list R Comma-separated list of one rendering style per layer. Use null value for default rendering (STYLES=&), or use style name from GetCapabilities response or SLD document, if applicable. Optional if SLD parameter is present.
FORMAT=output_format R Output format of map. Valid values are image/jpeg, image/png, and image/gif. Note: png represents png-8 bit or png-24 bit format depending on the selection made in the WMS Connector Administrator. If you plan to use transparency, you must select png or gif formats. Jpeg does not support transparency.
BGCOLOR=color_value O Hexidecimal red-blue-green color value for the map’s background color. Default is 0xFFFFFF (white).
TRANSPARENT=TRUE | FALSE O Map’s background transparency. Default is FALSE.
SLD=sld_url O URL of a styled layer descriptor file. See the WMS specification documentation for details.
EXCEPTIONS=exception_format O The format in which exceptions are reported. The default is application/vnd.ogc.se_xml. Other valid formats are application/vnd.ogc.inimage and application/vnd.ogc.se_blank.
REASPECT=TRUE | FALSE
(Vendor Specific)
O Used if clients want to reaspect the BBOX. The default is based on the selection made in the WMS Connector Administrator.
SERVICENAME=service_name
(vendor specific)
O By default, the capabilities of the default WMS service is queried. If you want to use a non-default service, the service name must be included in the URL.

Examples

Example 1: Using the minimum amount of parameters

This example shows the minimum number of parameters needed to make a successful GetMap request. This example uses the default WMS service, which is the service name you added in the WMS Connector Administrator. For more information about the Administrator page, see Using the WMS Connector Administrator.

http://<hostname>/<deploy_name>/com.esri.wms.Esrimap?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=Oceans,Countries,Cities&STYLES=&SRS=EPSG:4326&BBOX=-124,21,-66,49&WIDTH=600&HEIGHT=400&FORMAT=image/png&

where


Example 2: Specifying a nondefault WMS service

In this next example, a nondefault WMS service is specified.

http://<hostname>/<deploy_name>/com.esri.wms.Esrimap?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=States,Cities&STYLES=&SRS=EPSG:4326&BBOX=-124,21,-66,49&WIDTH=600&HEIGHT=400&FORMAT=image/png&SERVICENAME=myService&

where

A second way to specify a non-default WMS service does not use the SERVICENAME parameter.

http://<hostname>/<deploy_name>/com.esri.wms.Esrimap/myService?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=States,Cities&STYLES=&SRS=EPSG:4326&BBOX=-124,21,-66,49&WIDTH=600&HEIGHT=400&FORMAT=image/png&

where

Example 3: Using optional parameters

In this following example, optional parameters are specified. This URL should be all on one line.

http://<hostname>/<deploy_name>/com.esri.wms.Esrimap/?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=States,Cities&STYLES=&SRS=EPSG:4326&BBOX=-124,21,-66,49&WIDTH=600&HEIGHT=400&FORMAT=image/png&SERVICENAME=myservice&
TRANSPARENT=TRUE&BGCOLOR=0xFF0000&EXCEPTIONS=application/vnd.ogc.se_blank&REASPECT=TRUE&

where

Note: Hard returns added to URLs for readability

Errors

By default, the GetMap response returns an XML structure containing error information if the WMS service detected an error and the EXCEPTIONS parameter was set to application/vnd.ogc.se_xml.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<ServiceExceptionReport version="1.1.1">
<ServiceException>
LAYERS LIST is empty
</ServiceException>
</ServiceExceptionReport>

With a GetMap request, exceptions can be handled two additional ways:

You will always receive an error if the HTTP request is improperly formatted or a required parameter is missing. Common error messages are:

Problem Error message
REQUEST missing Missing mandatory REQUEST parameter. Possibilities are {capabilities|GetCapabilities|map|GetMap|feature_info|GetFeatureInfo}
VERSION missing Missing VERSION | WMTVER parameter
LAYERS missing Missing LAYERS parameter or value
SRS missing Missing SRS parameter or value
BBOX missing Missing BBOX parameter or value
Invalid BBOX value Invalid BBOX value, NumberFormatException : For input string: <value>
WIDTH missing Missing WIDTH parameter or value
Invalid WIDTH value Invalid WIDTH value, NumberFormatException : For input string: <value>
HEIGHT missing Missing HEIGHT parameter or value
Invalid HEIGHT value Invalid HEIGHT value, NumberFormatException : For input string: <value>
FORMAT missing Missing FORMAT parameter or value
Invalid FORMAT value Invalid FORMAT value
Invalid layer name Layer with ID {id} does not exist

In some cases, an ArcIMS error message is returned. More information on these error messages is available in the Error Messages section of this help system.

Problem ArcIMS Error message
Requested image is too large Requested image is too big and cannot be created or invalid height or width were used.

This error message refers to ERR0924 for Image Services.
Requested service is not available Exception in GetMap reply.
[ERR0134] Requested service is not available.