Monitor mobile devices with the Geospatial Analytics service

Build a real-time location-monitoring application on IBM Bluemix with Geospatial Analytics and Node.js


The Internet of Things already connects billions of devices, with forecasts predicting steep growth rates in the coming years. Many of these devices, such as smartphones and connected vehicles, are mobile. Awareness of the location of on-the-move devices opens up exciting new application opportunities. Support for these new applications requires highly scalable services that can analyze high volumes of data in real time.

With the Geospatial Analytics service in IBM Bluemix™, you can monitor moving devices from the Internet of Things. The service tracks device locations in real time with respect to one or more geographic regions. Geospatial Analytics can be used as a building block in applications that support several use cases. For example, a retail business might want to monitor for potential customers nearby its stores and send them promotions via push notifications or tweets. Geospatial Analytics could also be used to detect connected motorists entering areas that they might want to avoid due to an accident, weather conditions, or other temporal event.

This tutorial explains how to obtain, run, and extend a starter application written in Node.js (with the help of the SDK for Node.js) that uses the Geospatial Analytics service. The geo-starter app uses:

  • A demo MQTT broker that generates simulated device information for an area near Las Vegas, Nevada.
  • The Geospatial Analytics service's REST API to configure the service to subscribe to an MQTT topic on the demo MQTT message broker. This subscription causes messages to flow to the service that include information about the current location of each device.
  • The service's REST API to define three geographic regions for the service to monitor. Two are defined only to trigger events when a device enters the region. One is defined to trigger events when a device enters or exits the region.

The service analyzes the location of each device with respect to the set of geographic regions that are defined and sends a region-location event back to MQTT when a device enters (or, optionally exits) a region. The geo-starter application processes the region-location events and displays them in an event listing, as illustrated in this flow diagram:

Block diagram of the geo-starter app's components
Block diagram of the geo-starter app's components

With Geospatial Analytics, the potential for new location-aware applications in the Internet of Things is limitless, with you setting the boundaries.

What you'll need to build your application

Run the appGet the code

Step 1. Create a Bluemix app and bind the Geospatial Analytics service

  1. Log in to Bluemix. In the dashboard, click the CREATE AN APP button. Find and click SDK for Node.js from the available runtimes in the catalog. Enter a name and host of your liking and click CREATE.
  2. On the application page, click the ADD A SERVICE button. Click the Geospatial Analytics service in the catalog (under Big Data) and click CREATE to bind it to your application.

Step 2. Obtain your own copy of the source code

To obtain your own copy of the source code, follow the steps below:

  1. Download the file (or click this tutorial's Get the code button).
  2. Save the exported file locally and extract its contents.
  3. Rename the directory that contains the extracted files to match the name of the app you created in Step 1.

Step 3. Deploy your app

Now you'll deploy the starter application as-is, without any code changes. Later in the tutorial, you'll have a chance to customize the application and redeploy it.

  1. From your OS command line, change to the directory containing your extracted application:
    cd myapp
  2. Run these commands to connect to the Bluemix instance of Cloud Foundry:
    cf api
    cf login
  3. Deploy your app:
cf push myapp

Step 4. View the running app

  1. In Bluemix, click your application's route to open the app. You see a basic web page with the title Welcome to the Geospatial Analytics Starter Application!: Screenshot of the welcome page
    Screenshot of the welcome page
  2. Use the parts of the page to see the status and results of the app:
    • The Application Flow section lists the steps that are being performed by the application and their status.
    • The Event List section displays region-location events as they are produced by the Geospatial Service and received by your application.
  3. On the same web page, click the geo-starter Visualizer link. The page that opens uses a map view to show the current location of the devices and the geographic regions that are being monitored: Screenshot of the visualizer page
    Screenshot of the visualizer page
  4. Back in Bluemix, bring up the service dashboard for your Geospatial Analytics service. You can access the dashboard in multiple ways, including by clicking the Geospatial Analytics icon in your application: Screenshot of the service icon
    The dashboard displays the current status of the service and service metrics, such as the number of device messages received from MQTT and the number of region-location events produced by the service.

Step 5. Review the source code

The geo-starter app is a complete yet simple application that requires no customization to run. To understand the app, examine its code:

  1. Open the app.js file to view the application logic. The code in app.js is organized around the five major steps performed by the application in this sequence:
    1. Extract the environment information required to use the Geospatial Analytics REST API.
    2. Start the Geospatial Analytics service, connecting it to a MQTT demo server.
    3. Create three geographic regions for the service to monitor.
    4. Process events generated when devices enter and exit the region.
    5. Stop the Geospatial Analytics service after the event target is reached.
  2. Examine the extraction of the Geospatial Analytics service credentials more closely. As with other Bluemix services and add-ons, you must extract the credentials and service URLs for the Geospatial Analytics service from the VCAP_SERVICES runtime environment variable.

    Here's an example of the environment information that's returned for the Geospatial Analytics service:

      "Geospatial Analytics": {
        "name": "Geospatial Analytics",
        "label": "Geospatial Analytics",
        "plan": "Free",
        "credentials": {
          "geo_host": "",
          "geo_port": 443,
          "start_path": "/jax-rs/geo/start/service_instances/xxxx/service_bindings/xxxx",
          "stop_path": "/jax-rs/geo/stop/service_instances/xxxx/service_bindings/xxxx",
          "restart_path": "/jax-rs/geo/restart/service_instances/xxxx/service_bindings/xxxx",
          "add_region_path": "/jax-rs/geo/addRegion/service_instances/xxxx/service_bindings/xxxxx",
          "remove_region_path": "/jax-rs/geo/removeRegion/service_instances/xxxx/service_bindings/xxxx",
          "status_path": "/jax-rs/geo/status/service_instances/xxxx/service_bindings/xxxx",
          "dashboard_path": "/jax-rs/dashboard/xxxx",
          "userid": "xxxxx",
          "password": "xxxxx"

    The credentials subsection includes all the information required to use the REST API of the service. The host and port for the API are provided. Paths are provided to each of the operations in the API. Finally, a userid and password are provided that must be passed on each call to the API.
  3. Examine the code for calling the start operation on the service's REST API. Here's a subset of this code:
    jsonObject = JSON.stringify({
            "mqtt_uri" :  "",
            "mqtt_input_topics" : "iot-2/cars/#",
            "mqtt_notify_topic" : notify_topic_string,
            "device_id_attr_name" : "ID",
            "latitude_attr_name" : "lat",
            "longitude_attr_name" : "lon"

    The configuration parameters to the start call are composed into a JSON object. The parameters describe the MQTT URI and topics that the service should subscribe to. In addition, a variable containing the topic where the service should publish region-location events is specified. Last, the code describes the attributes of the device message that the service should use to identify the a device and determine its location.
  4. Examine the code for adding regions to monitor using the addRegion operation on the service's REST API. Here's a subset:
    jsonObject = JSON.stringify({
            "regions" : [
               "region_type" : "regular",
               "name" : "Promo Zone 1",
               "notifyOnExit" : "false",
               "center_latitude" : "36.121",
               "center_longitude" : "-115.224",
               "number_of_sides" : "10",
               "distance_to_vertices" : "850"
               "region_type" : "regular",
               "name" : "Promo Zone 2",
               "notifyOnExit" : "false",
               "center_latitude" : "36.121",
               "center_longitude" : "-115.101",
               "number_of_sides" : "10",
               "distance_to_vertices" : "750"
               "region_type" : "custom",
               "name" : "Tracking Path",
               "notifyOnExit" : "true",
               "polygon" : [
       {"latitude" : "36.135795", "longitude" : "-115.148584"},
    {"latitude" : "36.134096", "longitude" : "-115.148584"},
    {"latitude" : "36.133247", "longitude" : "-115.147254"},
    {"latitude" : "36.131427", "longitude" : "-115.147254"},
    {"latitude" : "36.131427", "longitude" : "-115.148327"},
    {"latitude" : "36.132849", "longitude" : "-115.148327"},
    {"latitude" : "36.133698", "longitude" : "-115.149657"},
    {"latitude" : "36.135795", "longitude" : "-115.149657"}

    The code shown here again focuses on the parameters passed to the operation. Two regular polygon regions are created by specifying their center point and radius. A third custom region is specified by listing the points that define the irregular polygon.

Step 6. Customize or extend the app

Now that you're familiar with the starter app, you might want to modify the application's source code to customize it or extend it in any of several interesting ways:

  • To make the application run longer, you could change the event_target variable's value from 100 to a higher number.
  • Add or alter the geographic regions being monitored by the service by modifying the parameters passed to the addRegion operation of the service's REST API.
  • Take an action when a region-location event is received. For example, you might want to extend the application to send a push notification to a device when it enters a monitored region.
  • Switch to a different MQTT data source. If you have your own MQTT data source, you can modify the parameters passed to the start operation of the service's REST API to use your own MQTT.

To modify the app:

  1. Plan your modifications.
  2. Change the source code to reflect your desired customizations.
  3. Deploy the modified application.


Keeping track of connected devices that are on the move is not as impossible as it might seem at first. With the Geospatial Analytics service, you can monitor the location of these devices in real time with respect to geographic regions that are important to you. The starter application used in this tutorial demonstrates how you can control the Geospatial Analytics service to meet your requirements. With Geospatial Analytics, the potential for new location-aware applications in the Internet of Things is limitless, with you setting the boundaries.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Mobile development, Cloud computing, Information Management, Cognitive computing, Internet of Things
ArticleTitle=Monitor mobile devices with the Geospatial Analytics service