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. Reaspect is valid only with Image Services. It is not valid with ArcIMS ArcMap Image Services and is always TRUE.
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

• <hostname> is the URL domain name for your site such as www.esri.com or a fully qualified machine name.
• <deploy_name> is the name you assigned to the Web application when you deployed the WMS Connector. The recommended deployment name is "wmsconnector".
• http://<hostname>/<deploy_name>/com.esri.wms.Esrimap? is the full URL to access the WMS Connector on an ArcIMS site.
• VERSION=1.1.1 is the WMS request version.
• REQUEST=GetMap is the request name.
• LAYERS=Oceans,Countries,Cities is the list of layers requested in the service. You do not need to request all layers, but each layer name that you do request must be valid.
• STYLES= is the styles reference. This should be left empty.
• SRS=EPSG:4326 is the spatial reference value. This example uses geographic WGS 1984.
• BBOX=-124,21,-66,49 is the bounding box in SRS coordinates of the map. In this example, the coordinates are in decimal degrees.
• WIDTH=600&HEIGHT=400 are the width and height of the requested image in pixels.
• FORMAT=image/png is the requested image format.

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

• SERVICENAME=myService is the service you are requesting. The service name is case sensitive.

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

• /myService is the service you are requesting. The name is case sensitive and must be placed before the question mark (?) in the URL.

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

• TRANSPARENT=TRUE determines whether the specified background color is transparent.
• BGCOLOR=0xFF0000 is the specified background color. In this case, it is set to red. In this example, all red pixels will be transparent. Although this parameter is specified as "background color", all pixels of the specified BGCOLOR will become transparent, even if it is part of the map.
• EXCEPTIONS=application/vnd.ogc.se_blank is the exceptions output format. In this example a blank map is returned.
• REASPECT=TRUE determines whether the map is reaspected or not. When reaspect is FALSE, the pixels representing the map area are stretched to fit into the requested height and width.

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:

• Application/vnd.ogc.se_inimage. An image is returned with the message as part of the image.
• Application/vnd.ogc.se_blank. A blank map is returned. No error message is included.

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 and ERR0515 for ArcMap Image Services.
Requested service is not available	Exception in GetMap reply. [ERR0134] Requested service is not available.