Geospatial data plays an essential role in various fields such as urban planning, environmental monitoring, and logistics. One of the most widely used methods for serving geospatial data as maps over the web is the Web Map Service (WMS).

A Web Map Service (WMS) is a standard protocol developed by the Open Geospatial Consortium (OGC) that allows users to request and display maps generated by a server from spatial data. WMS delivers map images in various formats (such as PNG, JPEG, or SVG), making it easy to integrate and display in web applications.

Well, we already know the definition! Now let's try to display the map using WMS as Map Background in APEX application. This article will be an extension of another article which you can find here: Oracle APEX 23.2 and Background Maps!

OpenStreetMap

OpenStreetMap (OSM) is a user-generated mapping platform that provides an open-source, detailed map of the world. Users can contribute and edit geospatial data, making the maps continuously updated and freely available for various uses, from navigation to urban planning.

The https://www.terrestris.de/en/demos/ website provides a variety of sample services that present the capabilities of OSM and I will try to set one of the example WMS as a Map Background in my Oracle APEX application.

WMS step by step

My WMS looks like this:

https://ows.terrestris.de/osm/service?

To properly display the map, to the above URL we need to add many parameters, according to the documentation which you can find here: link. Okay, but how do I know what the values ​​of all these parameters are?

Let's start with the fact that if I want to display the map as Map Background, APEX itself adds a few parameters. Here is the list:

• BBOX

• WIDTH

• HEIGHT

• REQUEST

• FORMAT

• SRS / CRS

So, we only need to define parameters such as:

• LAYERS

• STYLES

• VERSION

Where can I find the values ​​of the above parameters? We can use the GetCapabilities request which provides detailed metadata about the WMS (service and layer information, data formats, supported operations and versioning)

To get such information I need to define three parameters in my URL:

• SERVICE (mandatory)

• REQUEST (mandatory)

• VERSION (optional) - I use the latest version od WMS

My URL should look like this:

https://ows.terrestris.de/osm/service?
service=WMS
&request=GetCapabilities
&version=1.3.0

The above URL will return us information about the WMS in XML format. (You can just run it in your browser). In the appropriate sections I can find the values ​​of my parameters (Layer -> Name and Style -> Name)

    <Layer queryable="1">
      <Name>OSM-Overlay-WMS</Name>
      <Title>OSM Overlay WMS - by terrestris</Title>
      <LatLonBoundingBox minx="-180" miny="-88" maxx="180" maxy="88" />
      <BoundingBox SRS="EPSG:900913" minx="-20037508.3428" miny="-25819498.5135" maxx="20037508.3428" maxy="25819498.5135" />
      <BoundingBox SRS="EPSG:4326" minx="-180" miny="-88" maxx="180" maxy="88" />
      <BoundingBox SRS="EPSG:3857" minx="-20037508.3428" miny="-25819498.5135" maxx="20037508.3428" maxy="25819498.5135" />
      <Style>
          <Name>default</Name>
          <Title>default</Title>
          <LegendURL width="155" height="160">
              <Format>image/png</Format>
              <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:href="https://ows.terrestris.de/osm/service?styles=&amp;layer=OSM-Overlay-WMS&amp;service=WMS&amp;format=image%2Fpng&amp;sld_version=1.1.0&amp;request=GetLegendGraphic&amp;version=1.1.1"/>
          </LegendURL>
      </Style>
    </Layer>

So now my WMS URL for APEX Map Background should look like this:

https://ows.terrestris.de/osm/service?
service=WMS
&version=1.3.0
&layers=OSM-Overlay-WMS
&styles=default

Now, the only thing I need to do is to create a Map Background in my Oracle APEX application. If you want to know more you can check this link: Oracle APEX 23.2 and Background Maps!

1. Go to Shared Components

2. Select Map Backgrounds (Other Components section)

3. Click Create button.

4. Set Type = OGC WMS. Fill in Name and WMS URL (use the above URL)

5. In Oracle APEX application open Map region attributes and select the created Map Background

6. Save changes and run the page

My Map region looks like this:

In the Network tab of the browser I can see that WMS URL looks like this:

https://ows.terrestris.de/osm/service?
service=wms
&layers=OSM-Overlay-WMS
&version=1.3.0
&styles=default
&request=GetMap
&bbox=-20037508.342789244,0,-10018754.171394622,10018754.17139462
&format=image/png
&crs=EPSG:3857
&width=256
&height=256

And that's it! I just displayed Map Background using WMS!

Conclusions

I easily set up the Map Background using the WMS service. All I had to do was define 3 parameters (layers, styles, version), the rest was done for me by APEX in real low-code style. But as always, there were a few problems.

Depending on the WMS version, minor differences in parameters are required. For version 1.1.1, SRS (Spatial Reference System) should be added, for version 1.3.0, the CRS (Coordinate Reference System) parameter. These parameters define the BBOX value. APEX itself adds the CRS or SRS parameter depending on the defined VERSION. However, if I use uppercase letters in the URL, APEX adds incorrect parameters and does not display the map!

So for the WMS URL like this:

https://ows.terrestris.de/osm/service?
SERVICE=WMS
&VERSION=1.3.0
&LAYERS=OSM-Overlay-WMS
&STYLES=default

...the map will not be displayed. In the Network tab of the browser I will see the following URL:

https://ows.terrestris.de/osm/service?
SERVICE=WMS&VERSION=1.3.0
&LAYERS=OSM-Overlay-WMS
&STYLES=default
&request=GetMap
&bbox=-20037508.342789244,-10018754.171394622,-10018754.171394622,0
&format=image/png
&srs=EPSG:3857
&width=256
&height=256

The above URL for version=1.3.0 is missing the CRS parameter. If I run it in the browser I will get the message: missing parameters ['crs']. This problem appears in the latest version of APEX (24.1.2).