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.
Now that we understand the definition, let's move on to displaying a map using WMS as the Map Background in an Oracle APEX application. This article will be a continuation of a previous one, which you can find here: Oracle APEX 23.2 and Background Maps!
OpenStreetMap
OpenStreetMap (OSM) is a user-generated mapping platform that offers a detailed, open-source map of the world. Users can contribute and edit geospatial data, ensuring the maps are continuously updated and freely available for various applications, ranging from navigation to urban planning.
The website https://www.terrestris.de/en/demos/ provides a variety of sample services showcasing OSM's capabilities. I will demonstrate how to set one of these example WMS services 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, we need to add several parameters to the URL mentioned above, according to the documentation, which you can find here: link. But how do I know what the values of these parameters should be?
Let’s start with the fact that when I want to display the map as a Map Background, APEX automatically adds a few parameters. Here's the list:
BBOX
WIDTH
HEIGHT
REQUEST
FORMAT
SRS / CRS
So, we only need to define the following parameters:
LAYERS
STYLES
VERSION
Where can I find the values for these parameters? We can use a GetCapabilities request, which provides detailed metadata about the WMS, including service and layer information, data formats, supported operations, and versioning.
To get this information, I need to specify three parameters in my URL:
SERVICE (mandatory)
REQUEST (mandatory)
VERSION (optional) - I’ll use the latest version of WMS.
My URL should look like this:
https://ows.terrestris.de/osm/service?
service=WMS
&request=GetCapabilities
&version=1.3.0
The URL above will return information about the WMS in XML format (you can simply run it in your browser). In the relevant sections, I can find the values for 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=&layer=OSM-Overlay-WMS&service=WMS&format=image%2Fpng&sld_version=1.1.0&request=GetLegendGraphic&version=1.1.1"/>
</LegendURL>
</Style>
</Layer>
So now, my WMS URL for the 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 left 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!
Go to Shared Components.
Select Map Backgrounds (under the Other Components section).
Click the Create button.
Set Type to OGC WMS. Fill in Name and WMS URL (use the URL mentioned above).
In your Oracle APEX application, open the Map region attributes and select the newly created Map Background.
Save your changes and run the page.
My Map region looks like this:
In the browser's Network tab, I can see that the 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've successfully displayed a Map Background using WMS!
Conclusions
I easily set up the Map Background using the WMS service. All I had to do was define three parameters (LAYERS, STYLES, VERSION), while APEX handled the rest in a true low-code style. However, as always, there were a few issues.
Depending on the WMS version, slight differences in parameters are required. For version 1.1.1, the SRS (Spatial Reference System) must be added, while for version 1.3.0, the CRS (Coordinate Reference System) parameter is needed. These parameters define the BBOX value. APEX automatically adds the CRS or SRS parameter based on the defined VERSION. However, if I use uppercase letters in the URL, APEX adds incorrect parameters and fails to display the map!
For example, with a 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 browser's Network tab, I’ll 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
In the URL above, for VERSION=1.3.0, the CRS parameter is missing. If I run this URL in the browser, I will get the message: missing parameters ['crs']. This issue occurs in the latest version of APEX (24.1.2).