Introduction to Maps in Oracle APEX

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.

Map Region – The Default Map Component in APEX

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.

How to Store Spatial Data in the Database?

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.

GeoJSON

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

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.

Oracle APEX Maps – Different Layers

APEX allows you to represent layers in different forms. You have the following options:

• Points – simple points that allow y specific area of the map
• Lines – lines that lead from point A to B (or even A-B-C)

• Polygons – entire areas with boundaries determined by several straight lines

• Heat Maps – Point Objects displayed as a Heat Map. Useful, for example, for visualizing the density of point objects

• Extruded Polygons – polygons shown as 3D objects to visualize height. The height is based on a result column value

SDO_GEOMETRY Changes for Different Layers

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.

How to Create Your Map in 5 Easy Steps

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.

1. Choose Map Region – the native map display component
2. Choose layer type (the Points layer is the default one)
3. Choose the table with spatial data
4. Choose the data type (SDO_GEOMETRY/GeoJSON/VARCHAR and a column with  your geometry)
5. Click Run

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

Oracle APEX and Maps - Examples of Functionality

Below is a list of the things you can create using spatial components in APEX – without any additional effort on your part.

• Map region and layer settings – APEX gives you the ability to manage layers. You can display several layers on one map and customize the sizes, shapes, and colors of markers
• Map region's attributes – there are also some default attributes like MouseWheel Zoom, Rectangle Zoom, Distance Tool, Get Browser Location etc.
• Clickable map – you can also interact with your map directly using JavaScript, Dynamic Actions, and APEX components
• Create new geometry – dynamic actions allow you to get coordinates from the map and create new geometry
• Faceted search – you can combine Faceted Search with Map Region to build advanced filtering
• Display Map item (APEX version 21.2) – offers access to the minimap feature
• Geocoded Address Item (APEX version 21.2) – you can find locations by providing text data like country, street, or house number
• Sample Maps app – it offers a range of samples you can use

This is a very interesting topic that I’d like to cover in more detail in future articles, so be on the lookout!

Alternatives to the APEX’s Default Map Region Component

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.

1. Open Layers

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.

2. GeoServer

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.

3. Google Maps

And finally, we have Google Maps, which requires 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, etc. 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 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.

Conclusion

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. For example, I'll show you how to draw objects on the map with the use of MapLibre, and OpenLayers. Be sure to check these blog posts out!