July/August 2017
Maps play a pivotal role in many successful mobile applications. Apps such as Uber; Airbnb; and, of course, Google Maps and Apple Maps are used daily by millions, if not billions, of people. For mobile app users, knowing where the things they are interested in are located is a great benefit.
I’ve discussed maps before in this article space in a rather trivial use case of a single location on a map based on a human-readable address. Given the importance of maps in mobile apps, however, this is an area I want to revisit. With a combination of Oracle Mobile Application Accelerator and Oracle Mobile Cloud Service, this article will explore how to build an application that enables users to run spatial queries that return multiple locations within a radius of their current location. This might sound a bit dull and technical, but in a business context, this could be an app that enables you to query all the customers within 5,000 meters of your current location and a very handy thing for salespeople to know when they’re on the road and have time to visit other customers to make more sales.
As described in my previous map article, Oracle Mobile Application Accelerator supports the ability to plot maps. Oracle Mobile Cloud Service location-based services go beyond map plotting to enable mobile developers to store and retrieve information about places, such as physical addresses that might represent places of interest to a business; devices, such as iBeacons, Eddystone, and altBeacons, that an app can interact with as the user approaches a location not easily identified by GPS; and moving assets, which users may want to track to know the assets’ position relative to their current locations.
In this article, I’ll use Oracle Mobile Cloud Service’s location-based services capabilities and Oracle Mobile Application Accelerator’s map capabilities to support a solution to the traveling sales force’s customer location problem.
PrerequisitesTo follow the steps in this article, you will need access to Oracle Mobile Cloud Service, which you can obtain by clicking the Free Trial button on the Oracle Mobile Cloud Service home page. (You have the option to sign up for a trial account or free cloud credits.) After signing up for the trial and receiving approval, watch and follow the instructions in this video on how to set up and provision your Oracle Mobile Cloud Service instance. You will also need to set up two users with appropriate roles to build and access the application. First, you’ll need Jeff the developer, who will build a small application with Oracle Mobile Cloud Service and Oracle Mobile Application Accelerator. Second, you’ll need Mary the mobile user, who will actually use the Oracle Mobile Application Accelerator application built by Jeff. Review this small video on how to create both users. Finally, download the demo zip file that contains the files for this article, and unzip it on your desktop.
Location-Based ServicesAs mentioned earlier, location-based services within Oracle Mobile Cloud Service support the concepts of places, assets, and devices. At the most fundamental level, Oracle Mobile Cloud Service provides several REST APIs that enable you to create, manage, and query these data objects by ID or spatially relative to a latitude, longitude, and radius. Simply put, your business may have 1,000 customers located at different places identified by latitude and longitude, and Oracle Mobile Cloud Service will enable you to run the spatial query “Tell me all the customers within 5,000 meters.”
For the purposes of this article, because I can’t tell where you, the reader, reside, you’re not going to be able to build an app returning customers in your locality. Rather, you’re going to build an app with customers located around San Francisco, California, and assume you’re also located close to these customers. As such, the first task is to load the location-based services’ places data object with these San Francisco customers.
The resulting screen exposes the REST endpoints for maintaining places, assets, and devices in Oracle Mobile Cloud Service. By default, these will be empty for a new Oracle Mobile Cloud Service account or trial. Next, you’ll see the POST Add Places endpoint to create three customers located at different latitudes and longitudes for the Oracle Mobile Cloud Service application to use.
For Oracle Mobile Application Accelerator to display the location-based services places you just inserted into Oracle Mobile Cloud Service, it must access this data through a REST API. Unfortunately, Oracle Mobile Application Accelerator can’t talk directly to the location-based services REST API to extract places, so you must create your own custom API in Oracle Mobile Cloud Service to wrap a call to the places API. I’ve covered how to create REST APIs in previous articles in Oracle Magazine, so I’ll avoid covering this again. Instead you’ll import a prebuilt API that will do the work for you.
module.exports = function(service) {
service.get('/mobile/custom/spatial/customers', function(req,res) {
var sdk = req.oracleMobile;
var latitude = parseFloat(req.query.latitude);
var longitude = parseFloat(req.query.longitude);
var radius = parseInt(req.query.radius);
const spatialQuery = {"inGeoFence":{"gpsCircle":{
"latitude":latitude,"longitude":longitude,"radius":radius}}};
sdk.location.places.query(spatialQuery).then(
function (success) {
res.send(success.statusCode, success.result);
},
function (error) {
res.send(500, error.error);
});
});
};
As shown in the Node.js code, for the specific GET /mobile/custom/spatial/customers endpoint router function, the three query parameters are extracted from the request and then wrapped in a JSON object and fed into the SDK location.places.query method, which runs a spatial query on places within the radius of the latitude and longitude.
With the places API (named “spatial”) in place, you can now build your Oracle Mobile Application Accelerator app with a map. The goal will be to display on a map all the location-based services places within a radius of your current location.
However, as explained earlier, there is one snag for demonstration purposes, and that is that I simply don’t know where you are located. As such, when you created the places earlier in this article, they may be nowhere near you. For this demo app, you’re going to hardcode your latitude and longitude, but while proceeding through the steps, I’ll show you how to remove the hard coding and use your current location for the real application you may choose to build after reading this article.
In Oracle Mobile Application Accelerator, APIs are called business objects. In the following steps, you will bind the map to your places API, mapping the data fields of the map to the data supplied by the API as well as supplying values for the parameters.
The resulting wizard page is used to bind the API (aka business object) to the map. The first tab represents the mapping of the API’s returned payload to the required fields of the map on the right. The second tab represents the query parameters required by the API, which you must satisfy in some form. As you’ll recall, the API requires the user’s current latitude, longitude, and radius to search for places.
With the Data tab selected, note that the map wants a location value on the right. A location value is made up of a latitude and a longitude. With the Business Object option selected, note the data fields available from the API. Latitude and longitude are available in the address and gpsPoint fields.
To satisfy the original requirements for this app to show places within a radius of the user’s current location, you would select the Device Service option and then copy in the device’s Current Latitude and Current Longitude fields. However, as explained earlier, for demo purposes, you’ll hardcode these values.
On returning to the Oracle Mobile Application Accelerator designer, you may be a little disappointed to discover the single marker against a boring background again. By default, like the Live Preview option, the Oracle Mobile Application Accelerator designer shows only test data derived from the API. To see live data, you must run the application.
What excites me most about the mapping and spatial functionality provided through Oracle Mobile Application Accelerator and Oracle Mobile Cloud Service is that I’ve visited absolutely loads of customers who have address and location data in their enterprise databases but have never actually been able to display the data on a map. It’s mostly raw data, and it comes alive only when it’s on a map. As you saw in my previous article, where I plotted human-readable addresses on a map, and in this article, where I plotted numerous markers based on latitude and longitude, this simple-to-build functionality is now within reach, literally, of your mobile users.
TRY Oracle Mobile Cloud Service. |
Photography by Tatiana Nino, Unsplash
Integrated Cloud & Platform Services
