Web Map Service (WMS) Tutorial

Web Map Service (WMS) was created by the Open Geospatial Consortium (OGC) to “provide a simple HTTP interface for requesting geo-registered map images from one or more distributed geospatial databases.” To translate: WMS allows users to type a special kind of URL, called a WMS request, into their browser. This request gets sent to a WMS server, which is essentially a computer that stores a lot of maps. The server sends a map back to the user, in the format specified by the request.

To find a WMS server in the first place, simply search the web for “WMS server”.

WMS requests are made up of the address of the server the request is being sent to and a series of parameters. There are two types of request that are required for any WMS request: GetMap and GetCapabilities. Although GetCapabilities is usually the first request sent, it’s simpler than GetMap and not always required.

We’ll begin by looking at an example GetCapabilities request, since they’re less complicated, just to familiarize ourselves with the parts of a URL. THen we’ll look at how to make a GetMap request, because that’s the request you’ll be making most often, and then we’ll come back to GetCapabilities to learn how to use it.

https://www.gebco.net/data_and_products/gebco_web_services/web_map_service/mapserv?request=getcapabilities&service=wms&version=1.3.0

You can load maps through WMS using URLs just like you do when you load a webpage. URLs will take the form:

PROTOCOL://HOST/PATH?QUERY

PROTOCOL

Typically https, although on older sites you may still find http. The protocol is separate from the rest of the URL by ://

HOST

This will be the domain name that you typically think of as the website’s address such as gebco.net in the above example

PATH

This is the part of the URL that begins with a /, such as /data_and_products/gebco_web_services/web_map_service/mapserv in the above example. The path may or may not also end with a /

QUERY

The query string is separated from the rest of the URL by a ?. It is composed of parameters for the request along with the values assigned to those parameters. Parameters take the form NAME=VALUE and each name-value pair is separated by an &

In our previous example, the protocol is https, the host is gebco.net the path is /data_and_products/gebco_web_services/web_map_service/mapserv and the query contains three parameters

• version, which is set to 1.3.0
• service, which is set to WMS
• REQUEST, which is set to GetCapabilities

A GetMap request is the WMS request you’ll use to fetch a map for use in an SOS dataset. These requests contain a lot of parameters in their queries.

https://www.gebco.net/data_and_products/gebco_web_services/web_map_service/mapserv?request=getmap&service=wms&BBOX=-90,-180,90,360&crs=EPSG:4326&format=image/jpeg&layers=gebco_latest&width=1200&height=600&version=1.3.0

version=1.3.0

Specifies the version of the service you’re using. Sometimes parameters and response formats can change from version to version, so services allow you to request a specific version

service=WMS

Identifies this request as a WMS request

REQUEST=GetMap

REQUEST specifies the type of WMS request you’re making. In this case, it’s GetMap

LAYERS=gebco_latest

Tells the server which “layer” (which map) to return. This will vary depending on the map service you use, as they all offer different data

CRS=EPSG:4326

Defines the coordinate reference system. SOS requires CRS:84 or EPSG:4326

FORMAT=image/png

Defines the map’s format. In this case, we’re requesting the map as a jpeg (an image format)

HEIGHT=600

Defines the height of the image in pixels

WIDTH=1200

Defines the widht of the image in pixels

TRANSPARENT=TRUE

Sets the transparency of the map’s backgruond (this attribute is not present in the above example)

BBOX=-90,-180,90,360

Boundary box setting defines which piece of the map you’re looking at in degrees of latitude and longitude. For a world map, the coordinates shown above will show the complete map.

STYLES=rgb

Defines the “rendering style of the layer” (this attribute is not present in the above example)

If you have an existing GetMap request already, chances are you’ll have to check a few things and change a few others. The three changes that are required, minimum, are below:

1. After the HEIGHT= parameter, change whatever number is there to <PIXELHEIGHT>, spelled and capitalized exactly like that
2. After the WIDTH= parameter, change the number to <PIXELWIDTH>, spelled and capitalized exactly like that
3. After the BBOX parameter, change whatever numbers are there to <WEST>,<SOUTH>,<EAST>,<NORTH>, spelled and capitalized exactly like that

These changes are required for the SOS system, but they won’t work in a browser, because the keywords such as <PIXELHEIGHT> were created by the SOS team, not the designers of WMS

You should also check a few of the parameters to make sure they’re compatible with the SOS format.

1. CRS should equal CRS:84 or EPSG:4326. This parameter can’t be changed, so if it isn’t correct, you’ll need to find a different WMS server. If CRS= does not work, try SRS=
2. FORMAT should equal image/png or image/jpg

If these parameters are correct, you’re good to go! See the How to Display WMS Data on the Sphere section to proceed.

A GetCapabilities request will return an XML (Extensible Markup Language) document. If you aren’t familiar with markup languages, you can find more information on them here: http://en.wikipedia.org/wiki/Markup_language.

However, all you really need to know is that markup languages organize information by enclosing it with tags that describe what type of information it is. For example, to designate a title, an XML document will have the Title tags enclosing the actual title, like this:

<TITLE>Title of Map</TITLE>

Tags have an opening tag and a closing tag — the closing tag has a backslash in front of the word, inside the brackets.

The information you need from a GetCapabilities request is the name of the map layer, the CRS, and the formats available. To find the layer, you need to look for the <Layer> tag, followed by a <Name> tag instead of a <Title> tag. Layers don’t always contain maps; sometimes they contain metadata about the map instead. Usually, layers with maps will have the tag directly following the <Layer> tag, like this:

<Layer>
    <Name>MOD14A1_E_FIRE</Name>

You might not be able to determine which layer you want at first sight, just by looking at the tags containing information about the layer — in that case, simply try them out until you find one. See the next section for an explanation of how to do so. Similarly, to find the CRS, look for the tag <CRS>, and to find the format of a particular server, search for <Format>. As long as there is a format tag that contains the words image/jpg or image/png, SOS can use the map. However, the CRS must be CRS:84. You can do a simple word search in Windows by pressing Ctrl + F, which will bring up a little search box. Type in the tag you’re looking for, then use the up and down arrow keys to find multiple occurrences of your search term.

Once you’ve found the necessary information in the GetCapabilities page, you can start constructing your GetMap request. You’ll want to test your request in your browser before trying to put it onto the sphere, but some formats will have to be changed, as explained later. To make the request, keep everything up to the word GetCapabilities in your previous GetCapabilities request, then replace the word GetCapabilities with GetMap. This will change the request type. If you don’t already have parameters after your request, you’ll need to create them now, or modify them if you do have them. The parameters you need to create an SOS-ready WMS request are below.

If SOS requires a particular value, it has been filled in — however, not all of SOS’s requirements can be used in a browser. The keywords <PIXELHEIGHT>, <PIXELWIDTH>, and <WEST>,<SOUTH>,<EAST>,<NORTH> are in brackets not because they are XML tags, but because the SOS team (who created them) gave them that format to distinguish them from ordinary WMS parameters. The SOS software is the only thing that recognizes them. If you use them in a browser, you’ll get an error. Instead, fill in 1800 for HEIGHT and 3600 for WIDTH, and -180,-90,180,90 for BBOX if you’re testing your map in a browser.

• LAYERS equals the layer name you found using GetCapabilities
• CRS=CRS:84 or CRS=EPSG:4326
• FORMAT=image/png or FORMAT=image/jpg
• HEIGHT=<PIXELHEIGHT>
• WIDTH=<PIXELWIDTH>
• TRANSPARENT can equal TRUE or FALSE
• BBOX=<WEST>,<SOUTH>,<EAST>,<NORTH>
• STYLES usually equals rgb

Separate the parameters with & signs. Please note that spelling and capitalization have to be exactly as shown here. When you’re done, your request should look something like this for a browser: https://www.gebco.net/data_and_products/gebco_web_services/web_map_service/mapserv?request=getmap&service=wms&BBOX=-90,-180,90,360&crs=EPSG:4326&format=image/jpeg&layers=gebco_latest&width=1200&height=600&version=1.3.0.

And something like this for SOS:

https://www.gebco.net/data_and_products/gebco_web_services/web_map_service/mapserv?Service=WMS&WMS=worldmap&Version=1.1.0&Request=GetMap&BBox=<WEST>,<SOUTH>,<EAST>,<NORTH>&SRS=EPSG:4326&Width=&Height=&Layers=gebco_latest&Format=image/png

Note how HEIGHT, WIDTH, and BBOX have been changed.

Displaying WMS data is the same as displaying anything else — you’ll need to create a playlist.sos file. Use the layerdata tag to specify your WMS request. To tell the SOS software that the URL you’re giving it is a WMS request, add //WMS// right before the request, without spaces. Your tag should look like this:

layerdata = //WMS//https://www.gebco.net/data_and_products/gebco_web_services/web_map_service/mapserv?Service=WMS&WMS=worldmap&Version=1.1.0&Request=GetMap&BBox=<WEST>,<SOUTH>,<EAST>,<NORTH>&SRS=EPSG:4326&Width=<PIXELWIDTH>&Height=<PIXELHEIGHT>&Layers=gebco_latest&Format=image/png

Make sure the rest of your playlist.sos file is in order, and you should be good to go.