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 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. 

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.

👩‍🔧 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:

• (Spanish) https://www.snitcr.go.cr/ico_servicios_ogc
• (English) https://mrdata.usgs.gov/ 
• (English) https://www.gebco.net/data_and_products/gebco_web_services/web_map_service/
• (English) https://apps.nationalmap.gov/services/

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 can also connect the WMS/WMTS into a desktop application like ArcGIS or QGIS and access the layer names through the desktop application.

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

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’.

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!

🥽 Further troubleshooting approaches.

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

• If your layer is blank, first check your resolution. Some WMS layers will only be visible at certain resolutions, and you may need to zoom in to see the imagery. For example, the Mosaico5000 layer depicted above is only viewable when zoomed very far in.
• Next, double check the URL and the layer name for typos. 
• Make sure your layer is available in the correct projection. CEO uses 3857. Not all servers will provide this projection, in which case you will need to confer with the team responsible for the WMS/WMTS to have it added.
• If these don’t work, a good place to start is to make sure that your WMS server is working correctly by finding a WMS URL to an image of one of their map tiles. If you open this URL in your web browser, you should see that image load successfully. For example,
  • http://geos0.snitcr.go.cr/cgi-bin/web?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&FORMAT=image%2Fpng&TRANSPARENT=true&LAYERS=Mosaico5000&WIDTH=320&HEIGHT=320&CRS=EPSG%3A3857&STYLES=&FORMAT_OPTIONS=dpi%3A113&BBOX=-9275174.760236427%2C939258.2035682462%2C-9236039.001754416%2C978393.9620502564&map=ortofoto.map
  • https://geos1.snitcr.go.cr/Ortofoto2017/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image%2Fpng&TRANSPARENT=true&LAYERS=fotocentros_ortofoto_2017_5000&TILED=true&WIDTH=256&HEIGHT=256&SRS=EPSG%3A5367&gridSet=CRTM05&STYLES=&BBOX=348586.56637714803%2C738692.4676108168%2C912687.8695003731%2C1302793.770734042

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:

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!