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.
How Does it Work, Exactly?Permalink to How Does it Work, Exactly?
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.
URL FormatPermalink to URL Format
You can load maps through WMS using URLs just like you do when you load a webpage. URLs will take the form:
- Typically https, although on older sites you may still find http. The protocol is separate from the rest of the URL by ://
- This will be the domain name that you typically think of as the website’s address such as neowms.sci.gsfc.nasa.gov in the above example
- This is the part of the URL that begins with a /, such as /wms/wms in the above example. The path may or may not also end with a /
- 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 http, the host is neowms.sci.gsfc.nasa.gov the path is /wms/wms 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
GetMap RequestsPermalink to GetMap Requests
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.
Parameters for the GetMap RequestPermalink to Parameters for the GetMap Request
- 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
- Identifies this request as a WMS request
- REQUEST specifies the type of WMS request you’re making. In this case, it’s GetMap
- 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
- Defines the coordinate reference system. SOS requires CRS:84
- Defines the map’s format. In this case, we’re requesting the map as a PNG (an image format)
- Defines the height of the image in pixels
- Defines the widht of the image in pixels
- Sets the transparency of the map’s backgruond
- 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. However, the SOS team prefers if users use the parameter
<BOUNDING_BOX>to define BBOX, like this:
BBOX=<BOUNDING_BOX>. This will always give the full map
- Defines the “rendering style of the layer”
How to use an Existing GetMap RequestPermalink to How to use an Existing GetMap Request
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:
- After the HEIGHT= parameter, change whatever number is there to <IMAGE_HEIGHT>, spelled and capitalized exactly like that
- After the WIDTH= parameter, change the number to <IMAGE_WIDTH>
- After the BBOX parameter, change whatever numbers are there to <BOUNDING_BOX>
These changes are required for the SOS system, but they won’t work in a browser, because the keywords such as <IMAGE_HEIGHT> 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.
- 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
- FORMAT should equal image/png, image/jpg, or another SOS-supported image format
If these parameters are correct, you’re good to go! See the How to Display WMS Data on the Sphere section to proceed.
GetCapabilities RequestsPermalink to GetCapabilities Requests
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.
How to Find Relevant Information in a GetCapabilities RequestPermalink to How to Find Relevant Information in a GetCapabilities Request
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
<Layer> tag, like this:
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/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.
How to Create a GetMap RequestPermalink to How to Create a GetMap Request
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 <IMAGE_HEIGHT>, <IMAGE_WIDTH>, and <BOUNDING_BOX> 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
- FORMAT=image/png or FORMAT=image/jpg
- TRANSPARENT can equal TRUE or FALSE
- 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: http://neowms.sci.gsfc.nasa.gov/wms/wms?version=1.3.0&service=WMS&REQUEST=GetMap&LAYERS=MODAL2_D_CLD_CI&CRS=CRS:84&FORMAT=image/png&HEIGHT=1800&WIDTH=3600&TRANSPARENT=TRUE&BBOX=-180.0,-90.0,180.0,90.0&STYLES=rgb.
And something like this for SOS:
BBOX have been changed.
How to Display WMS Data on the SpherePermalink to How to Display WMS Data on the Sphere
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:
Make sure the rest of your playlist.sos file is in order, and you should be good to go.