Geospatial Analytics API

Live

Geospatial Analytics API

+ Day(s) remaining in the trial

Overview

Use the Geospatial Analytics application programming interface (API) to configure and control the Geospatial Analytics service from your application. The API is based on the representational state transfer (REST) architectural principles and is implemented with the HTTPS protocol.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.



Manage your keys
 

Global Parameters

This section contains global variables, which apply to all of the endpoint definitions of this API. You can use this section to set these variables once, and have the values pre-filled for every endpoint in the Documentation section. The values set can be used with the built-in testing. You can always override the value in the endpoint definition of the Documentation section.
Global variables

You must take this value from the service credentials, which can be accessed from the service dashboard.

Documentation

Geospatial Analytics API:

Region

Region
addRegion
Adds one or more regions to monitor to a running or stopped service. Requires that the service was started at least once. 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}

			https:///jax-rs/geo/addRegion/service_instances/{service_id}/service_bindings/{binding_id}
		
Keys
Global variables

rest_url

BASEURL , required

You must take this value from the service credentials, which can be accessed from the service dashboard.

Path and Query parameters

binding_id

URL , required

The bind ID established on the service Bind sequence.

service_id

URL , required

The service instance ID established on the service Provision sequence.

Request code
								
HttpResponse<String> response = Unirest.put("https:///%3Crest_url%3E/jax-rs/geo/addRegion/service_instances/{service_id}/service_bindings/{binding_id}") .header("accept", "application/json") .header("content-type", "application/json") .body("{\"center_latitude\":null,\"center_longitude\":null,\"distance_to_vertices\":null,\"minimumDwellTime\":null,\"name\":\"test\",\"notifyOnEntry\":true,\"notifyOnExit\":true,\"number_of_sides\":null,\"polygon\":\"undefined\",\"region_type\":\"undefined\",\"timeout\":true}") .asString();
Request model

center_latitude

DOUBLE , optional

The latitude of the center point of a regular region.

center_longitude

DOUBLE , optional

The latitude of the center point of a regular region.

distance_to_vertices

DOUBLE , optional

The distance, in meters, from the center point to any vertex of the regular polygon. This distance is the radius of the polygon.

minimumDwellTime

INTEGER , optional

The minimumDwellTime parameter is used for hangout detection. It is an integer value of seconds that enables the detection of a basic pattern about a moving entity's location called a hangout. For a given device, it is said to be hanging out or in a hangout if it has been dwelling in the same region for a period of time. Hangout events are generated if two conditions are met. First, the latitude and longitude of each consecutively reported device location indicate that the device is contained in this region, and second, that the period of time in question is at least minimumDwellTime seconds in duration. The first time a hangout is detected in a region, a Hangout event is produced. Following device locations that indicate the device is still in hangout will have an event type of 'Hangout-1', 'Hangout-2', etc. incrementally increasing the number for each device location received while the device remains in that region. Lastly, when a device location comes indicating the device is no longer in that region, a Hangout End event is produced. The default value if unspecified is set to null, which means no hangout events will be reported for this region.

name

STRING , optional

A name that identifies the region.

notifyOnEntry

BOOLEAN , optional

If notifyOnEntry is set to true, the region generates an Entry event when a device enters the region. When both this parameter and the notifyOnExit parameter are set to false and a minimumDwellTime is set, the region can be used to generate hangout events without generating entry and exit events. The default value if unspecified is set to true.

notifyOnExit

BOOLEAN , optional

If notifyOnExit is set to true, the region generates an Exit event when a device exits the region. The default value if unspecified is set to false.

number_of_sides

DOUBLE , optional

The number of sides for the regular polygon.

polygon

STRING , optional

An ordered set of points that define a closed poly-line. A side is added between the last point and the first point to complete the polygon.

region_type

STRING , optional

Defines the type of region. Valid values are regular or custom.

timeout

BOOLEAN , optional

The timeout parameter is used for exit detection and hangout detection. It is an integer value of seconds that specifies how long, in seconds, before the location of a device relative to this region is considered stale. A device location is considered stale if an update to the location has not been received in the last timeout seconds. When a new location is received for a stale device, and this device was contained in a given region, the device is no longer treated as being contained. This means that no Exit event is generated. A new Entry event is generated if the device location is within this region. The Hangout state is reset as if this is the first time this device location was encountered to be relative to this region and if the device was in a hang out, you do not receive the Hangout End event. The default value if unspecified is set to null, which means no check for stale location data will be performed for this region.

Request example
{
  "center_latitude": undefined,
  "center_longitude": undefined,
  "distance_to_vertices": undefined,
  "minimumDwellTime": undefined,
  "name": "test",
  "notifyOnEntry": false,
  "notifyOnExit": false,
  "number_of_sides": undefined,
  "polygon": "undefined",
  "region_type": "undefined",
  "timeout": false
}
Response model

200

OK

Response example

200

OK

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}

			https:///jax-rs/geo/removeRegion/service_instances/{service_id}/service_bindings/{binding_id}
		
Keys
Global variables

rest_url

BASEURL , required

You must take this value from the service credentials, which can be accessed from the service dashboard.

Path and Query parameters

binding_id

URL , required

The bind ID established on the service Bind sequence.

service_id

URL , required

The service instance ID established on the service Provision sequence.

Request code
								
HttpResponse<String> response = Unirest.put("https:///%3Crest_url%3E/jax-rs/geo/removeRegion/service_instances/{service_id}/service_bindings/{binding_id}") .header("accept", "application/json") .header("content-type", "application/json") .body("{\"region_name\":\"Kiosk 3\",\"region_type\":\"custom\"}") .asString();
Request model

region_name

STRING , optional

A name that identifies the region.

region_type

STRING , optional

Defines the type of region. Valid values are regular or custom.

Request example
{
  "region_name": "Kiosk 3",
  "region_type": "custom"
}
Response model

200

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

Response example

200

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

Loading content...