Web Map Service (WMS)
The OGC Web Map Service standard allows GeoServer to serve map images on demand. This page documents the implementation details, request parameters, and configuration options.
Overview
GeoServer implements the OGC Web Map Service specification to provide map images to clients such as Leaflet, OpenLayers, QGIS, and mobile mapping applications. The WMS service supports versions 1.1.1 and 1.3.0.
Unlike the Web Feature Service (WFS), which returns vector data, WMS renders data as raster images (PNG, JPEG, GIF, SVG) on the server side. This reduces client-side processing load and ensures consistent styling across all map consumers.
GetCapabilities Request
The GetCapabilities operation describes the metadata, available layers, supported operations, and bounding boxes of the WMS service. Clients typically call this first to discover available data.
Request Example
GET /geoserver/wms?SERVICE=WMS\&VERSION=1.3.0\&REQUEST=GetCapabilities HTTP/1.1
Host: geo.example.com
The response is an XML document conforming to the WMS 1.3.0 Capabilities schema. Key elements include <Layer> hierarchies, <CRS> support, and <OutputFormat> listings.
GetMap Request
The GetMap operation returns a map image representing the requested layers, extent, size, and style.
Required Parameters
The following parameters must be included in every GetMap request:
SERVICE=WMS\nVERSION=1.3.0\nREQUEST=GetMap\nLAYERS=workspace:layer_name\nSTYLES=\nCRS=EPSG:4326\nBBOX=-180,-90,180,90\nWIDTH=800\nHEIGHT=600\nFORMAT=image/png
Response
The server returns a binary image response with the Content-Type matching the requested format (e.g., image/png).
GetFeatureInfo Request
GetFeatureInfo allows clients to query map pixels and retrieve attribute data for features at that location. This is commonly used for click-to-inspect map interactions.
SERVICE=WMS\nVERSION=1.3.0\nREQUEST=GetFeatureInfo\nLAYERS=workspace:layer_name\nCRS=EPSG:4326\nBBOX=-180,-90,180,90\nWIDTH=800\nHEIGHT=600\nQUERY_LAYERS=workspace:layer_name\nINFO_FORMAT=text/html\nX=100\nY=200
The X and Y parameters specify the pixel coordinate to query. The INFO_FORMAT parameter determines the output format; GeoServer supports text/html, application/json, and text/xml.
Standard Parameters Reference
GeoServer supports all mandatory and common optional parameters defined by the OGC WMS 1.1.1 and 1.3.0 specifications.
| Parameter | Required | Description |
|---|---|---|
| SERVICE | Yes | Must be WMS. |
| REQUEST | Yes | Operation name: GetCapabilities, GetMap, or GetFeatureInfo. |
| VERSION | Yes | WMS version. GeoServer supports 1.1.1 and 1.3.0. Default: 1.1.1. |
| LAYERS | Yes (GetMap/GetFeatureInfo) | Comma-separated list of layer names. Format: workspace:layer or just layer if unique. |
| STYLES | No | Comma-separated list of style names corresponding to LAYERS. Use '' for no style or default. |
| CRS | Yes (v1.3.0) | Coordinate Reference System of the map image (e.g., EPSG:4326, EPSG:3857). Use SRS for v1.1.1. |
| BBOX | Yes (GetMap) | Bounding box in the order defined by the CRS axis order. For v1.3.0 + EPSG:4326: south,west,north,east. |
| WIDTH | Yes (GetMap) | Map image width in pixels. |
| HEIGHT | Yes (GetMap) | Map image height in pixels. |
| FORMAT | Yes (GetMap) | Output MIME type. Common values: image/png, image/jpeg, image/gif, image/svg+xml. |
| TRANSPARENT | No | If true, the background color is transparent. Supported for formats that allow it (PNG, GIF). |
| SRS | Yes (v1.1.1) | Alias for CRS in version 1.1.1. |
GeoServer WMS Extensions
GeoServer provides several non-standard parameters and capabilities that extend the base WMS specification for enhanced functionality.
Extended BBOX and SRS
GeoServer supports the EXTENDED_SRS parameter to advertise additional coordinate systems beyond the standard EPSG list, including Web Mercator and various local projections.
WMS Time Dimension
For temporal datasets, GeoServer supports the TIME parameter in GetMap requests, allowing clients to request maps for specific timestamps or time ranges.
?LAYERS=temporal_layer\&TIME=2023-01-01/2023-01-07
Mapfish Print Integration
GeoServer integrates with MapFish to provide high-resolution PDF/PNG printing capabilities via a specialized WMS endpoint: /geoserver/mapfish/print.
Styling with SLD
GeoServer uses Styled Layer Descriptor (SLD) XML documents to define how WMS layers are rendered. While WMS clients can request style names, advanced styling requires SLD.
To apply a custom SLD style via WMS, use the SLD_BODY or SLD parameter, or reference a style uploaded to the GeoServer Data Directory.
Caching and GeoWebCache
GeoServer includes GeoWebCache (GWC) to serve WMS tiles from a pre-rendered cache, significantly improving performance for frequently accessed layers.
To use GWC with WMS, clients can use the standard WMS endpoints, and GeoServer will automatically serve cached tiles if the request matches a seed gridset (e.g., EPSG:900913 for Web Mercator).
Troubleshooting
Common Issues
- Empty Map: Verify that BBOX coordinates match the axis order of the requested CRS. WMS 1.3.0 with EPSG:4326 expects lat,lon axis order.
- Layer Not Found: Ensure the layer name includes the workspace prefix (e.g., topp:states) if multiple workspaces contain layers with the same name.
- CORS Errors: Enable CORS filters in GeoServer web.xml or configure a reverse proxy (Nginx/Apache) to handle cross-origin requests.
- Performance: If GetMap responses are slow, check layer indexes, enable GWC caching, or optimize the source data geometry.