In EarthRanger, integrating Web Map Service (WMS) basemaps requires constructing a service URL based on the WMS service's capabilities. This guide will walk you through the steps to build a functional WMS service URL for use within EarthRanger, ensuring that the URL includes the necessary parameters for proper map rendering. 
 

Introduction to Building a WMS URL
 

When working with a WMS service, the first step is to obtain the GetCapabilities response, which provides the details necessary to build your WMS URL. This is typically done by appending the ?service=wms&request=getcapabilities to your WMS service URL. For example:  

https://ortos.dgterritorio.gov.pt/wms/ortosat2023?service=wms&request=getcapabilities

The GetCapabilities response will be in XML format and will list the available parameters that you will use to construct the full WMS URL to integrate the basemap into EarthRanger. 
 

Constructing the WMS URL 
 

After receiving the GetCapabilities XML, you will construct the final WMS URL by including various parameters that are either explicitly listed in the capabilities or fixed by the WMS standard.  

Final URL Example:
https://ortos.dgterritorio.gov.pt/wms/ortosat2023?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&FORMAT=image/png&TRANSPARENT=true&LAYERS=OrtoSat2023&STYLES=&WIDTH=256&HEIGHT=256&CRS=EPSG:3857&BBOX={bbox-epsg-3857}

Breakdown of the URL Parameters

Here is a detailed explanation of each parameter included in the WMS URL:
 

1. Base URL:  https://ortos.dgterritorio.gov.pt/wms/ortosat2023?

• Source: Extracted from the GetCapabilities XML <OnlineResource> tag.
• Explanation: This is the base endpoint for making WMS GetMap requests.  

2. SERVICE=WMS: SERVICE=WMS

• Source: Fixed by the WMS standard.
• Explanation: Always set to WMS as required by the WMS specification.

3. VERSION=1.3.0: VERSION=1.3.0

• Source: Extracted from the <WMS_Capabilities> root node.
• Explanation: This indicates the version of the WMS specification that the service supports.
   

4. REQUEST=GetMap: REQUEST=GetMap

• Source: Fixed by the WMS standard.
• Explanation: This is the request type to fetch map images.

5. FORMAT=image/png: FORMAT=image/png

• Source: Chosen from formats listed under <GetMap> in the XML capabilities document.
• Explanation: Specifies the image format for the map. image/png is chosen here and can also be a JPG or a JPEG.  

6. TRANSPARENT=true: TRANSPARENT=true

• Source: Optional parameter set by the user.
• Explanation: This ensures the map background is transparent, useful for overlaying maps.

7. LAYERS=OrtoSat2023: LAYERS=OrtoSat2023

• Source: Extracted from the <Layer> definition in XML.
• Explanation: Specifies the layer to display, in this case, OrtoSat2023. 

8. STYLES=: STYLES=

• Source: Required by the WMS standard, but left empty if no specific style is defined.
• Explanation: Since no specific style is defined in the XML, leave this empty.

9. WIDTH=256 & HEIGHT=256: WIDTH=256&HEIGHT=256

• Source: Client-defined within limits specified in the XML.
• Explanation: These values determine the size of the requested map image. Typically, 256x256 pixels is a standard size.

10. CRS=EPSG:3857: CRS=EPSG:3857 

• Source: Extracted from the <CRS> tags within the layer's metadata in the XML.
• Explanation: Specifies the Coordinate Reference System (CRS) used for map projection. EPSG:3857 is commonly used for web maps.

11. BBOX={bbox-epsg-3857}: BBOX={bbox-epsg-3857} 

• Source: Dynamically generated by the client at runtime.
• Explanation: This parameter represents the bounding box for the map image, typically provided as {bbox-epsg-3857} in most mapping frameworks.
   

Up Next: Exporting and Preparing EarthRanger Data