Maps are a vital feature for many applications made in Oracle APEX. How to offer this functionality in your software? My name is Lech Cieślik, and I’m an experienced Oracle APEX Developer working at Pretius Low-Code. In this blog post, I’ll explain how to use the default Map Region component.
I’ll also describe alternative solutions you can integrate with Oracle APEX to offer map functionality. Some of them might be better than Map Region in specific circumstances.
First, I’d like to take a moment to talk about Map Region, which is the basic map component in Oracle APEX,since the main part of the article will revolve around it.
Map Region was introduced in Oracle APEX version 21.1. You can use a local database or REST Service as the data source. Since APEX version 22.1 Map Regions feature is based on the MapLibre JavaScript library (check the documentation). You can modify it using the JavaScript API (thanks to the mapRegion interface and getObject method). There are also many ready-made examples and plugins available on the MapLibre website.
Now, let’s talk about storing spatial data in the database. I’ll base my example on a specific point on the map – Caprese Michelangelo – a small Italian village. Below are this island’s geographic coordinates. The longitude and latitude can be stored in two VARCHAR columns, and you can show them as a single point on the map.
There are also other options – we can store spatial data in GeoJSON (CLOB / VARCHAR column) or SDO_GEOMETRY (SDO_GEOMETRY COLUMN) formats.
If you use GeoJSON, the representation of the data is quite simple. There’s a NAME attribute with a Caprese value and geographic data like a coordinates table which is our point. It looks like this:
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"properties" : {"Name" : "Caprese"},
"geometry": {
"type": "Point",
"coordinates": [11.983333, 43.65]
}
}]
SDO_GEOMETRY is a bit more complicated. Look at the example below:
SDO_GEOMETRY( 2001, 8307, SDO_POINT_TYPE( 11.983333, 43.65, NULL), NULL, NULL )
The first attribute stores information about the geometry type. The 2001 code marks a two-dimensional point. The 8307 value is the designation of the SDO_SRID, the coordinate system I use (World Geodetic System, to be specific). Finally, SDO_POINT are the coordinates of my point.
APEX allows you to represent layers in different forms. You have the following options:
Of course, SDO_GEOMETRY will also look different for different layers. For example, look at the example below – SDO_GEOMETRY for the 2D polygon form.
SDO_GTYPE = 2003 defines our form as a two-dimensional polygon, and SDO_ELEM_INFO_ARRAY is a set of parameters that describe it. Offset = 1 means the first coordinate from SDO_ORDINATE_ARRAY is the first point of our polygon. The remaining information defines the exterior polygon. Lines indicate connections between the points. Finally, the SDO_ORDINATE_ARRAY is an array of geographic coordinates of the polygons.
Theory is useful, but in the end, the most important thing is creating maps for your own projects. Here’s a quick, step-by-step instruction on how to do that.
As you can see, the basics are pretty straightforward. Let’s take a look at some of the things you can do with maps out-of-the-box (or almost out-of-the-box).
Below is a list of the things you can create using spatial components in APEX – without any additional effort on your part.
This is a very interesting topic that I’d like to cover in more detail in future articles, so be on the lookout!
Everyone uses maps in different ways. While the most popular question is usually „where?”, sometimes „when?”, „what?”, and „how?” can be equally important.
Depending on the project you work on, you might need navigation, heat maps, drawing components, route mapping, up-to-date data, and so on. Because of this, there is no such thing as a perfect map, and sometimes you’ll have to integrate APEX with different tools to meet the client’s requirements.
The OpenLayers library is the first good alternative to Map Region. It’s an open-source JavaScript library that allows you to create maps, display layers, and markers. It provides easy-to-access customization options, and you can also use the API to build more complex functionalities. The OpenLayers website offers 230 ready-made examples that you can use in your applications.
GeoServer is also a good choice. It’s another open-source software server written in Java that allows users to share and edit geospatial data. The main goal of the GeoServer is to make spatial layers (vector, raster data) available via services like Web Map Service (returns an image of a map) or Web Feature Service (returns features with geometry and attributes that clients can use in geospatial analysis). Check out the documentation.
With GeoServer, it’s really about uploading a file with geographic data to the server. It then makes this file available through the WMS or WFS service. And such a service can be easily consumed by APEX REST DATA SOURCE and used in your APEX app. Using such a server gives you many possibilities. You can use various maps available on the Internet, and you can easily manage new versions. When an update happens, you simply need to replace the map on the server.
And finally, we have Google Maps, which require no introduction, really. The service allows you to search for objects, view maps, photos of the Earth’s surface, and panoramic views from the street level (so-called Street View). You can also look at real-time traffic flow, plan travel routes, and much more. I believe everyone has used Google Maps at least once in their lives, be it on vacation in an unknown place, or to find a specific restaurant in your local area. It’s the service most people imagine when they’re asked about maps on the Internet.
And with good reason! Google has created an API that allows you to insert your own map on pretty much any website. To do that, you need a JavaScript and a key that can be obtained by any user of a Google Account. Of course, there are various rate limits here you have to keep in mind – if your needs exceed them, you’ll have to pay. See the documentation for answers to any specific questions.
And with that, we’re at the end of my introduction to using maps in Oracle APEX applications. I hope you’ll find the information I’ve gathered here useful. As you can see, there are plenty of options and possibilities, and this is really just an introduction to the subject. My plan is to follow this article with a few others. I’ll describe Map Region’s attributes in much more detail, and I’ll also show you how to draw objects on the map with the use of MapLibre, and OpenLayers. Be sure to check these blog posts out! And if you have any questions, you can always reach out to me at lcieslik@pretius.com. Finally, there are many other APEX-related articles on the Pretius blog, so check them out:
