Introduction

You use the Geospatial Analytics service to monitor when devices are entering or leaving locations that you specify. Expand the boundaries of your application. Leverage real-time geospatial analytics to track when devices enter, leave or hang out in defined regions. Powered by IBM® Streaming Analytics for IBM Cloud. Use the Geospatial Analytics application programming interface (API) to configure and control the Geospatial Analytics service from your application.

Error handling

The Geospatial Analytics service API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Methods

restart

Restarts the monitoring of regions after the service was stopped.

PUT /restart/service_instances/{service_id}/service_bindings/{binding_id}
Request

Path Parameters

  • The bind ID established on the service Bind sequence.

  • The service instance ID established on the service Provision sequence.

Response

Status Code

  • A status code of 200 accompanied with a valid JSON body indicates success.

Example responses

start

Starts a service that is already provisioned in IBM Cloud. When the service is started, it processes device messages from the MQTT data source that is identified by the parameters you set. If you call start on a service that is already running, the service stops and then starts again with the parameters from this invocation of start.
The messages that flow from the MQTT data source must be in JSON format and do the following:

  • Uniquely identify the device that the message is about.
  • Provide a value for the current latitude of the device.
  • Provide a value for the current longitude of the device.
PUT /start/service_instances/{service_id}/service_bindings/{binding_id}
Request

Path Parameters

  • The bind ID established on the service Bind sequence.

  • The service instance ID established on the service Provision sequence.

The MQTT user ID. This parameter is optional. It may or may not be required by your MQTT broker.

Response

Status Code

  • Successful response

Example responses

status

Returns status information about the service and returns the set of regions that are currently defined.

GET /status/service_instances/{service_id}/service_bindings/{binding_id}
Request

Path Parameters

  • The bind ID established on the service Bind sequence.

  • The service instance ID established on the service Provision sequence.

Response

Status Code

  • Successful response

Example responses

stop

Stops the monitoring of regions until the service is restarted.

PUT /stop/service_instances/{service_id}/service_bindings/{binding_id}
Request

Path Parameters

  • The bind ID established on the service Bind sequence.

  • The service instance ID established on the service Provision sequence.

Response

Status Code

  • Successful response

Example responses

addRegion

Adds one or more regions to monitor to a running or stopped service. You can configure regions to generate events on device entry, device exit and/or hangout. A region can be specified in one of two ways:

  • A regular polygon with a center point, radius, and number of sides.
  • A custom polygon, which specifies the set of points that outline it. You can configure a region to generate any combination of entry, exit, and hangout events based on the default values and/or the values specified for the notifyOnEntry, notifyOnExit, and minimumDwellTime. You must configure each region to generate at least one of those three event types.
PUT /addRegion/service_instances/{service_id}/service_bindings/{binding_id}
Request

Path Parameters

  • The bind ID established on the service Bind sequence.

  • The service instance ID established on the service Provision sequence.

A set of one or more region definitions.

Response

Status Code

  • Successful response

Example responses

removeRegion

Removes a region from a running or stopped service so that the region is no longer monitored.

PUT /removeRegion/service_instances/{service_id}/service_bindings/{binding_id}
Request

Path Parameters

  • The bind ID established on the service Bind sequence.

  • The service instance ID established on the service Provision sequence.

A name that identifies the region.

Response

Status Code

  • Successful response

Example responses