WMS URL Builder

How the WMS URL Builder works, and what it assumes

A WMS GetMap request is an ordinary HTTP GET whose query string carries the whole request. The builder assembles it, checks each value against the specification and reports what it changed. Colons, commas and slashes are left unencoded because all three are legal in a query string and the URL is far easier to read and to paste that way.

Three differences between the two versions matter in practice. The parameter naming the coordinate system is SRS in 1.1.1 and CRS in 1.3.0. The BBOX is always x, y in 1.1.1, but in 1.3.0 it follows the axis order the CRS itself defines — so EPSG:4326, which EPSG defines as latitude then longitude, takes minimum latitude first. And 1.3.0 added CRS:84, which is WGS 84 with longitude first, added precisely so a request can sidestep the question. You always type the box in x, y order and the builder rewrites it when the version and CRS require it.

What it cannot do is tell you the request will work, because nothing is sent anywhere. Whether that server publishes that layer, supports that CRS, can produce that format or will accept an image that size are all questions only its GetCapabilities document answers, and that URL is built for you alongside the request. The checks here are the ones that can be made without asking: the bounding box has four numbers in the right order, the image size is a sane number of pixels, the aspect ratios of the box and the image agree, and a transparent JPEG is flagged as the contradiction it is.

Using the WMS URL Builder

• Testing whether a WMS layer renders at all, by pasting a request straight into a browser.
• Working out why a request returns a blank image, which is usually the axis order or a CRS the layer does not support.
• Producing a static map image from a service for a document or a report.
• Building the template URL that an application will fill in at run time.

A worked example

The same view of EPSG:4326 requested in both versions, entered as -124.7, 24.5, -66.9, 49.4:

1.1.1  ...&SRS=EPSG:4326&BBOX=-124.7,24.5,-66.9,49.4&WIDTH=800&HEIGHT=344
1.3.0  ...&CRS=EPSG:4326&BBOX=24.5,-124.7,49.4,-66.9&WIDTH=800&HEIGHT=344

and the GetCapabilities URL for the same endpoint:

https://example.org/geoserver/wms?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities

Open that first. It lists the layer names exactly as the server spells them, the CRS codes each layer supports, the image formats on offer and the MaxWidth and MaxHeight the server will accept — which is four of the five things that make a GetMap request fail.

Where this comes up in GIS work

1. Enter the WMS endpoint URL. Any query parameters it already carries, such as a MapServer map= value, are kept.
2. Enter one or more layer names, comma-separated, as the server's GetCapabilities document spells them.
3. Choose the WMS version and the CRS, and enter the bounding box as minimum x, minimum y, maximum x, maximum y.
4. Set the image width, height and format, and tick Transparent for an overlay.
5. Copy the GetMap URL, or open the GetCapabilities URL first to check the layer names and limits.

When the output looks wrong

The bounding box has a different aspect ratio from the image

The map will be stretched or squashed, because the server fits the box you asked for into the pixels you asked for. Adjust the width, the height or the box until the ratios agree; the builder shows both numbers so you can see by how much they differ.

TRANSPARENT=TRUE has no effect

JPEG has no alpha channel, so a transparent JPEG is not a thing. Use image/png for any layer meant to sit over another one, and keep JPEG for opaque aerial imagery, where it is much smaller.

The endpoint URL already carried some of these parameters

Anything the builder sets itself is dropped from the original URL, so no parameter is sent twice. Server-specific parameters that the builder does not set, such as MapServer's map= value, are kept in place at the front of the query.

This CRS is not in the offline EPSG subset

The builder could not check its axis order, so it wrote the box in x, y order and said so. Confirm the order against the server's GetCapabilities document before relying on the URL.

Questions about the WMS URL Builder