Using your own data in CEO: Connecting WMS/WMTS

We often hear from users that they have data that they would like to add to their Collect Earth Online (CEO) projects. Fortunately, CEO provides two easy ways to add your own imagery to your projects. The first is by connecting your own imagery via Web Map Service (WMS) or Web Map Tile Service (WMTS), and the second is by connecting your imagery hosted in Google Earth Engine (GEE). In this blog post, we will focus on connecting WMS/WMTS data sources to CEO.

🤝 Connecting your WMS/WMTS to CEO

WMS and WMTS provide specifications for serving georeferenced maps over the internet. Many national datasets are available through this protocol.

You may be familiar with using WMS or WMTS imagery in desktop applications such as ArcGIS or QGIS. Like these desktop applications, CEO can display WMS and WMTS imagery though the institutional imagery feature.

The Institutional Imagery addition form for WMS Imagery.
The Institutional Imagery addition form for WMS Imagery.

The first step of preparing to connect to your WMS/WMTS with CEO is checking that your WMS/WMTS is compatible with CEO. CEO requests data in EPSG:3857. Your WMS/WMTS server is responsible for reprojecting the imagery it hosts into this projection. Fortunately, most WMS/WMTS will do this automatically. Once your data is loaded, you can always visually check that they align with known good imagery, such as MapBox. 

To connect your WMS/WMTS to CEO, you need to gather three pieces of information: the base URL for your WMS/WMTS, the layer name that you want, and any parameters your WMS/WMTS requires to serve imagery. If you need help gathering this information, there are more details provided in the next section.

The basic steps to connect your WMS or WMTS imagery are:

  • Go to the “Imagery” button at the top of your CEO institution, and click “Add New Imagery.”
  • Select “WMS Imagery” as the under Select Type.
  • Add a title, which will be the displayed name of the imagery.
  • Add the attribution, which assigns credit to the group who collected or owns the imagery. This will appear on the data collection screen while users perform data collection tasks.
  • Add the URL, which should be the http:// or https:// URL of your WMS/WMTS, and not contain a query string
  • Add the layer name from your server that you want to display.
  • Add any parameters for your layer required by the WMS/WMTS.
  • And finally, if you need to use a proxy for your WMS/WMTS, check the Proxy Imagery box. You may need this option if you need to obfuscate a key for your WMS or WMTS, and you use a proxy–a server between CEO and your WMS/WMTS–to do so. 
Filled in WMS imagery form for GEBCO data.
Filled in WMS imagery form for GEBCO data.

Once you’ve added the layer from the WMS/WMTS, you can add it to any of your projects and leverage the imagery during data collection.

An example WMS image from GEBCO viewed in the CEO data collection screen.
An example WMS image from GEBCO viewed in the CEO data collection screen.

👩‍🔧 Locating information for WMS/WMTS connections

However, sometimes users have difficulty identifying the correct URL, layer name, and parameters to use to connect their imagery successfully. Here’s some tips that we recommend to help you find this information.

First, find the information page on your WMS/WMTS. These websites will frequently contain the necessary information to connect your WMS/WMTS to CEO. Sometimes your desired data source will have a more complex information page, with information about the data and then links to multiple WMS/WMTS. Some examples include:

When looking at this information, the first piece of information to look for is to locate the WMS URL. For example, https://geos1.snitcr.go.cr/Ortofoto2017/wms?VERSION=1.1.1.

An important thing to note is that everything after the ? in your WMS/WMTS URL is a parameter. When adding it to CEO, it should not be considered part of the URL. However, you will want to include the ? when you add your URL to CEO–but don’t worry, we’ll add it automatically if you forget!

The second piece of information to look for is the layer names that are available. The information page will frequently contain a list of layers that can be viewed with the WMS/WMTS. Note that sometimes your layer may have multiple names, so through the web interface you must make sure you are viewing the correct name.

You may need to view the layer’s metadata through the online portal in order to find the correct WMS/WMTS layer name.
You may need to view the layer’s metadata through the online portal in order to find the correct WMS/WMTS layer name.

You can also connect the WMS/WMTS into a desktop application like ArcGIS or QGIS and access the layer names through the desktop application.

The GEBCO WMS connection and its layers connected to QGIS.
The GEBCO WMS connection and its layers connected to QGIS.

You can then inspect the Layer Properties in order to find the information you need to connect the WMS/WMTS layer to CEO.

Layer properties of the GEBCO_2020_Grid_3 layer as displayed in QGIS.
Layer properties of the GEBCO_2020_Grid_3 layer as displayed in QGIS.

If you cannot load data into a desktop GIS and your WMS/WMTS only uses an XML file that does not have any style information associated with it, you can still find the layer name but it is more difficult. In this case, the information is in a difficult to read document tree. If this is the case, and you can’t load the data into a desktop GIS, search for “Layer” and look for the text <Layer> with <Name>, <Title> and <Abstract> information fields that follow it. The <Name> text will be what you are looking for. In this example, the name is ‘GEBCO_2020_Grid_3’.

An example of a layer for a WMS server that does not include XML styling, so you must look at the document tree.
An example of a layer for a WMS server that does not include XML styling, so you must look at the document tree.

The final piece is to identify the parameters. In our URLs, everything after the ? is a parameter, separated by the “&” character. Common things that you may see in URLs include:

  • SERVICE=WMS
  • version=1.1.1 (or another version number)
  • request=GetCapabilities

We do not want to include any of these three in our CEO parameters. This is because

  • “Service=WMS” is handled automatically by CEO,
  • “version=1.1.1” or another version is likewise handled, and
  •  “request=GetCapabilities” is a request to the WMS server to provide a list of capabilities (e.g. layer names), not the maps themselves. 

Other parameters may be necessary. For example, some WMS/WMTS have a “map” parameter that is necessary. Other parameters you might see include “crs” (generally not needed), “format” (also generally not needed). We suggest reading additional resources on the WMS GetMap function to help you to identify any additional parameters your WMS requires to serve imagery.

If you do load your WMS in a desktop GIS, you can use the Layer Properties interface to help you find the appropriate properties to include.

Now that we have the crucial information, we can connect the WMS to CEO.

  • In CEO, navigate to your Institutional Imagery page.
  • Create a new imagery layer of type WMS Imagery.
  • For Title, add your desired name. This might be the WMS layer name, the WMS name, some combination of these, etc.
  • Add the Attribution for your imagery.
  • Type in your WMS URL (only the portion before the ?) that you identified above.
  • Type in your WMS Layer Name.
  • Type in your additional WMS Parameters. These need to be written as a JSON object.
    • For example, “map=ortofoto.map” (a unique parameter required by a specific WMS)
    • Becomes {“MAP”:”ortofoto.map”}. Note the straight “”.
    • If you do not have any parameters type {}.
  • Double check that you entered all information correctly and press Save!
Completed WMS Imagery form for a WMS where an additional WMS Parameter is needed.
Completed WMS Imagery form for a WMS where an additional WMS Parameter is needed.
The imagery in the Data Collection interface.
The imagery in the Data Collection interface.

🥽 Further troubleshooting approaches.

If after you try these steps you are still having trouble, here are some additional troubleshooting hints.

Note that this server requires SRS instead of CRS. Both are OGC compliant. While you’re creating the working WMS URL, you might get the following error:

400 no SRS error.

Constructing these can be difficult. One of the best ways to construct them is to use your browsers’ console or developer tools, looking at the “Network” pane. When you visit your project in CEO and try to load the data, it should populate with multiple requests for the different map images. You can double click on these in order to visit the individual image. If this doesn’t work, you can try adding or changing the URL until an image appears.

Use your browsers’ console or developer tools to try to get a list of the individual images.

Clicking on one of these (e.g. https://www.gebco.net/data_and_products/gebco_web_services/2020/mapserv?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&FORMAT=image%2Fpng&TRANSPARENT=true&LAYERS=GEBCO_2020_Grid_3&WIDTH=256&HEIGHT=256&CRS=EPSG%3A3857&STYLES=&BBOX=-8766409.899970295%2C-313086.06785608083%2C-8609866.866042254%2C-156543.03392803986) will attempt to show a single image. 

If you haven’t configured the WMS correctly, clicking on one of these requests gives an error message. For example, here’s an example error:

<?xml version=’1.0′ encoding=”ISO-8859-1″ standalone=”no” ?>
<!DOCTYPE ServiceExceptionReport SYSTEM “http://schemas.opengis.net/wms/1.1.1/exception_1_1_1.dtd”>
<ServiceExceptionReport version=”1.1.1″>
<ServiceException code=”MissingParameterValue”>
msWMSLoadGetMapParams(): WMS server error. Missing required parameter SRS
</ServiceException>
</ServiceExceptionReport>

For this WMS, getting rid of the version=1.1.1 parameter resolved the configuration issue.

We suggest reading resources on the WMS GetMap function to help you interpret these errors, for example: http://opengeospatial.github.io/e-learning/wms/text/operations.html#getmap

 

CEO would like to thank its ongoing funders FAO, NASA–USAID SERVIR, and SilvaCarbon, a US government program. Thanks also to CEO’s technology partners: Norway’s International Climate & Forests Initiative for funding open high-resolution data availability; Planet for providing high-resolution imagery; and the Google Earth Engine team for creating a platform for Earth science data and analysis.

Collect Earth Online is working constantly to improve the user experience, and your feedback is invaluable. If you have ideas to share, please write to support@collect.earth.

Thank you!

Search Our Blog

Generic selectors
Exact matches only
Search in title
Search in content