RadioCloud Application Platform API Reference NAV Navbar
Logo
shell

Introduction

RadioCloud Application Platform is a multi-tenant platform for configuring and hosting a variety of Sensor based IOT applications. It provides services such as device management, application configuration, complex event processing, as well as ingestion, storage, analysis, and integration of device data. It also includes a rich set of API for Asset Tracking application.

Customer

Customer is at the root of the hierarchy. It can represent an entire organization, or a department within an organization. Customer has unique Name and ID.

Properties Description
name Name of the Customer
zipcode Zip Code
email_address Email ID of the Customer

Customer has many Applications and Zonal Activators

Person

A person represents an individual user of the system. A Customer can have 1 or more Users.

Properties Description
username Unique name accross the system
password Password
clientID Autogenerated Client ID for using services like ActiveMQ.
authority
ROLE_ADMIN
Manages applications, zones, users, devices and attaches/detaches Nodes to devices.
ROLE_USER
Has read-only access. Can attach/detach
ROLE_SERVICE_LEVEL
This role is an auto generated role for each Customer. It can be used for processes such as the ActiveMQ message listeners.

Create

curl -u username:password
  -H "Content-Type: application/json"
  -X POST -d
  '{
    "username":"test_user",
    "password":"test_password",
    "authority":"ROLE_USER"
  }' 
  "/api.cognosos.net/person"

The above command returns JSON structured like this:

{
    "accountExpired": false,
    "accountLocked": false,
    "clientID": null,
    "enabled": true,
    "passwordExpired": false,
    "username": "test_user"
}

This endpoint creates a new person.

HTTP Request

POST /api.cognosos.net/person

Headers

Content-Type: application/json

Request Body

Field Required Type Description
username true String Unique Username
password true String Password
authority true Enum = [ROLE_USER, ROLE_ADMIN, ROLE_SERVICE_LEVEL] Authority for the new user

Response Body

201 CREATED

Content-Type: application/json

Field Description
username Username
clientID Client ID for ROLE_SERVICE_LEVEL users
enabled Enabled
accountExpired Account Expired
accountLocked Account Locked
passwordExpired Password Expired

Update

curl -u username:password
  -H "Content-Type: application/json"
  -X PUT -d
  '{
    "password":"test_password",
    "accountLocked":true
  }' 
  "/api.cognosos.net/person/1"

The above command returns JSON structured like this:

{
    "accountExpired": true,
    "accountLocked": false,
    "clientID": null,
    "enabled": true,
    "passwordExpired": false,
    "username": "test_user"
}

This endpoint can be used to update password of the person or to lock a person.

HTTP Request

PUT /api.cognosos.net/person/{id}

Headers

Content-Type: application/json

Request Body

Field Required Type Description
accountLocked false Boolean To Lock a user
password false String New Password

Response Body

200 OK

Content-Type: application/json

Field Description
username Username
clientID Client ID for ROLE_SERVICE_LEVEL users
enabled Enabled
accountExpired Account Expired
accountLocked Account Locked
passwordExpired Password Expired

Application

Application is the highest level entity when deploying a RadioCloud based IOT service.

Application has Nodes, 989-942-9681, Sites, 917-201-7352, Zonal Activators, and Subscriptions.

Application belongs to Customer and has a 802-884-3053

A Customer can define 1 or more instance of an Application as necessary.
For example, if a car dealers has multiple locations, an Application can be created for each location.

Application Type defines the behaviour of an application. For example, an Asset Tracker application keeps track of the location of the assets being tracked, as well as its historical movements. A Parking application keeps track of the status of a parking spot, as well as its usage details.

Properties Type Description
name String Display Name for the application
code String Unique Customer managed application Code across the system.
latitude String The latitude of the home location of the application
longitude String The longitude of the home location of the application
gps_granularity Double Any location change below this granularity is ignored
status Enum = [0, 1] Application Status
0 - ARCHIVED
1 - ACTIVE
activeMQ_publish_severity_level Enum = [1, 2, 3, 4] ActiveMQ severity level
1 - INFO
2 - HIGH
3 - CRITICAL
4 - NONE
non_responsive_detection_frequency Integer
total_devices Integer Total Number of devices belonging to the application

Get

curl -u username:password
  "/api.cognosos.net/application"

The above command returns JSON structured like this:

[
  {
    "activeMQ_publish_severity_level": 1,
    "application_type": {
      "name": "Asset Tracker"
    },
    "code": "AAA",
    "gps_granularity": 0,
    "latitude": "99.99999",
    "longitude": "-99.99999",
    "name": "Application 1",
    "non_responsive_detection_frequency": 3,
    "status": 1,
    "total_devices": 16000
  },
  {
    "activeMQ_publish_severity_level": 4,
    "application_type": {
      "name": "Asset Tracker"
    },
    "code": "AAB",
    "gps_granularity": 0,
    "latitude": "33.75306799999999",
    "longitude": "-84.3852819",
    "name": "Application 2",
    "non_responsive_detection_frequency": 3,
    "status": 1,
    "total_devices": 10000
  }
]

Get all applications belonging to a customer

HTTP Request

GET /api.cognosos.net/application

Request Parameters

Field Required Type Description
name false String Filter list by name
code false String Filter list by Application code
status false Integer Filter list by status (Archived or Active)
activeMQ_publish_severity_level false Integer Filter list by ActiveMQ Severity Level

Response Body

200 OK

Content-Type: application/json

Field Type Description
activeMQ_publish_severity_level Integer ActiveMQ Severity Level
application_type.name String Name of the Application type
code String Application Code
gps_granularity Double GPS Granularity
latitude String Application Latitude
longitude String Application Longitude
name String Application Name
non_responsive_detection_frequency Integer
status Integer Archived or Active
total_devices Integer Total Number of Devices

Custom Field

A Custom Field belongs to an Application and a 4069279112 would define the 601-670-6149 for this field.
For example, a parking lot application tracking cars can have custom fields for car attributes such as Color, Make, Model, etc.

Properties Type Description
name String Name of the Custom Field

Custom Field Value

Custom Field Value belongs to a node and is the value for the 437-239-8732 defined while creating an Application.

Properties Type Description
value String Value of the Custom Field

Node

Node corresponds to a physical asset/thing being tracked. Node belongs to an Application and has a unique asset_identifier accross application. Node can be attached/detached to/from a (610) 327-4269 belonging to same application. Node is considered Active when it is attached to a (651) 674-1169 and Inactive when it is not.

Properties Type Description
asset_identifier String The value that uniquely identifies this asset accross application. For example, in case of an automobile, this would be the VIN number
device_id Long The ID of the device attached to this Asset/Node. If device_id is 0 or null, then Node is not attached to any device.
latitude String The latitude of the current location of this Node/Asset
longitude String The longitude of the current location of this Node/Asset
location_url String Google maps url for the location
current_zone String Name of the current zone, if the Node is inside one. Semi-colon separated list if node is in multiple zones.
status Enum = [0,1,2] The status of the Node/Asset.
0 - Inactive
1 - Active
2 - Not Responding

Node has many 410-834-5571, Custom Field Values

Attach

curl -u username:password
  "/api.cognosos.net/node/attach?
  application_code=AAC&device_id=2201&asset_identifier=car&color=red"

The above command returns JSON structured like this:

{
  "id": 17,
  "application": {
    "id": 4,
    "code": "AAC",
    "name": "AT 3"
  },
  "asset_identifier": "car",
  "current_zone": null,
  "device_id": 2201,
  "latitude": null,
  "longitude": null,
  "location_url": null,
  "status": 1,
  "custom_field_values": [
    {
      "custom_field": "color",
      "value": "red",
      "id":1
    }
  ],
  "battery_level": 255,
  "battery_status": 0,
  "internal_temperature": 255,
  "signal_strength": null
}

This endpoint attaches a Device specified by device_id to the Node specified by the asset_identifier. If the Node is already attached to another Device, it will automatically be detached from that Device. If the Device corresponding to device_id is attached to another Node, that association will also be detached.

If the Node doesn’t exist in the system, it will be added. While adding a new node to the system, values for Custom Field can also be specified as request parameters. Sensors with default thresholds will be created for the new node.

HTTP Request

GET /api.cognosos.net/node/attach

Request Parameters

Parameter Required Description
asset_identifier true Unique Identifier for the Node
device_id true ID of the Device
application_code true Application Code
custom_field_name false Custom Field defined while creating Application

Response Body

200 OK If Node already exist in the system.

201 CREATED If new Node is created.

Content-Type: application/json

Field Type Description
id Long Node ID
asset_identifier String Unique identifier for the Node
current_zone String null if new Node
custom_field_values Array 2363449958
device_id Long ID of the Device
latitude String null if new Node
longitude String null if new Node
location_url String null if new Node
status Integer Node Status

Detach

curl -u username:password
  "/api.cognosos.net/node/detach?
  application_code=AAC&asset_identifier=car"

The above command returns JSON structured like this:

{
  "id": 17,
  "application": {
    "id": 4,
    "code": "AAC",
    "name": "AT 3"
  },
  "asset_identifier": "car",
  "current_zone": null,
  "device_id": 0,
  "latitude": null,
  "longitude": null,
  "location_url": null,
  "status": 0,
  "custom_field_values": [
    {
      "custom_field": "color",
      "value": "red",
      "id":1
    }
  ]
}

Detaches the Node identified by asset_identifier from the attached Device, if it is attached to one. An event is published to the topic, if so.

HTTP Request

GET /api.cognosos.net/node/detach

URL Parameters

Parameter Required Description
asset_identifier or device_id true Unique Identifier for the Node or Device ID
application_code true Application Code

Response Body

200 OK

Content-Type: application/json

Field Type Description
id Long Node ID
asset_identifier String Unique identifier for the Node
current_zone String null if new Node
custom_field_values Array Custom Field Values
device_id Long ID of the Device
latitude String null if new Node
longitude String null if new Node
location_url String null if new Node
status Integer Node Status

Get

curl -u username:password
  "/api.cognosos.net/node?application_code=AAA"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "application": {
      "id": 1,
      "code": "AAA",
      "name": "Asset Tracker"
    },
    "asset_identifier": "test_asset_2201",
    "current_zone": "1;2",
    "device_id": 2201,
    "latitude": "33.69605",
    "longitude": "-84.62221",
    "location_url": "/www.google.com/maps?q=33.69605 -84.62221",
    "status": 1
  },
  {
    "id": 2,
    "application": {
      "id": 1,
      "code": "AAA",
      "name": "Asset Tracker"
    },
    "asset_identifier": "test_asset_2202",
    "current_zone": "",
    "device_id": 2202,
    "latitude": "33.69615",
    "longitude": "-84.62227",
    "location_url": "/www.google.com/maps?q=33.69615 -84.62227",
    "status": 1
  },
  {
    "id": 3,
    "application": {
      "id": 1,
      "code": "AAA",
      "name": "Asset Tracker"
    },
    "asset_identifier": "test_asset_2203",
    "current_zone": "",
    "device_id": 2203,
    "latitude": "33.6963",
    "longitude": "-84.62236",
    "location_url": "/www.google.com/maps?q=33.6963 -84.62236",
    "status": 1
  }
]

Get list of Nodes for an Application

HTTP Request

GET /api.cognosos.net/node

Request Parameter

Field Required Type Description
application_code true String Filter list by Application
asset_identifier false String Filter list by Asset Identifier
status false Integer Filter list by status
device_id false Long Filter list by Device ID
current_zone false String Filter list by current zone.
no_current_zone false String If specified, returns list of Nodes that are not in any zone
max false Integer Max number of Nodes that are returned. Defaults to 200, max 20,000
battery_threshold false Float Returns Node whose attached device has battery level less than the specified value
signal_threhsold false Float Returns Node whose attached device has signal strength less than the specified value

Response Body

200 OK

Content-Type: application/json

Field Type Description
id Integer Node ID
application Object Application Code, ID and Name
asset_identifier String Asset Identifier
current_zone String Semi-colon separated list of Zone ID
device_id Long ID of the device attached, if any
latitude String current Latitude
longitude String current Longitude
location_url String Google maps url for the location
status Integer Status

Get Node Details

curl -u username:password
  "/api.cognosos.net/node"

The above command returns JSON structured like this:

{
  "id": 17,
  "application": {
    "id": 4,
    "code": "AAC",
    "name": "AT 3"
  },
  "asset_identifier": "car",
  "current_zone": null,
  "device_id": 2201,
  "latitude": null,
  "longitude": null,
  "location_url": null,
  "status": 1,
  "custom_field_values": [
    {
      "custom_field": "color",
      "value": "red",
      "id":1
    }
  ],
  "battery_level": 255,
  "battery_status": 0,
  "internal_temperature": 255,
  "signal_strength": null
}

Get Details of the Node

HTTP Request

GET /api.cognosos.net/node/details

Request Parameter

Field Required Type Description
node_id true Long Node ID

Response Body

200 OK

Content-Type: application/json

Field Type Description
id Integer Node ID
application String Application
asset_identifier String Asset Identifier
current_zone String Semi-colon separated list of Zone ID
latitude String current Latitude
longitude String current Longitude
device_id Long ID of the device attached, if any
status Integer Status
location_url String Google maps url for the location
custom_field_values Object 9085721911
battery_level Float Battery Value of Device attached
battery_status Float Battery Status of Device attached
internal_temperature Float Internal Temperature of Device attached
signal_strength Float Signal Strength of Device attached

Zone

A Zone is a contiguous area that belongs to an 3182024621. This is generally used for geo-fencing. If a Node enters or leaves a zone, an (567) 237-9765 will be triggered.

Properties Type Description
name String The Name of the Zone
site_id Long ID of Site to which Zone belongs
latitude String
longitude String
perimeter String The lat/long co-ordinates of the Zone
area Double Area of the Zone.
max_count_threshold String The maximum number of nodes that should ideally be in this Zone. If the count crosses this maximum value, an Event is triggered. However, the system doesn’t prevent from more nodes being added to this Zone
min_count_threshold String The minimum Nodes that should ideally be in this Zone. If the count falls below this manimum value, an Event is triggered.
node_count Long Number of Nodes in this Zone
capacity Long Capacity of the Zone
status Enum = [-1,1] The status of the Zone.
(-1) - ARCHIVED
1 - IN_USE

Create

curl -u username:password
  -H "Content-Type: application/json"
  -X POST -d
  '{
    "name":"test_zone",
    "perimeter":"33.4554 64.23432,33.7832 65.42342,33.4534 65.324242,33.4554 64.23432",
    "latitude":"33.4554",
    "longitude":"64.23432",
    "area":120.12,
    "capacity": 100
  }' 
  "/api.cognosos.net/zones?application_code=AAA"

The above command returns JSON structured like this:

{
    "id": 162,
    "dateCreated": "2017-12-14T15:43:34Z",
    "area":120.12,
    "capacity":100,
    "latitude": "33.4554",
    "longitude": "64.23432",
    "max_count_threshold": null,
    "min_count_threshold": null,
    "name": "test_zone",
    "node_count": null,
    "perimeter": "33.4554 64.23432,33.7832 65.42342,33.4534 65.324242,33.4554 64.23432",
    "site_id": 0,
    "status": 1
}

This endpoint creates a new zone.

HTTP Request

POST /api.cognosos.net/zones?application_code={code}

Headers

Content-Type: application/json

Request Body

Field Required Type Description
name true String The Name of the Zone
latitude false String
longitude false String
perimeter true String The lat/long co-ordinates of the Zone
area false Double Area of the Zone.
max_count_threshold false String The maximum number of nodes that should ideally be in this Zone. If the count crosses this maximum value, an Event is triggered. However, the system doesn’t prevent from more nodes being added to this Zone
min_count_threshold false String The minimum Nodes that should ideally be in this Zone. If the count falls below this manimum value, an Event is triggered.
capacity false Long Capacity of the Zone

Response Body

201 CREATED

Content-Type: application/json

Field Description
name The Name of the Zone
site_id ID of Site to which Zone belongs
latitude
longitude
perimeter The lat/long co-ordinates of the Zone
area Area of the Zone.
max_count_threshold The maximum number of nodes that should ideally be in this Zone. If the count crosses this maximum value, an Event is triggered. However, the system doesn’t prevent from more nodes being added to this Zone
min_count_threshold The minimum Nodes that should ideally be in this Zone. If the count falls below this manimum value, an Event is triggered.
node_count Number of Nodes in this Zone
status The status of the Zone.
(-1) - ARCHIVED
1 - IN_USE
capacity Capacity of the Zone

Update

curl -u username:password
  -H "Content-Type: application/json"
  -X PUT -d
  '{
    "name":"test_zone A"
  }' 
  "/api.cognosos.net/zones/162"

The above command returns JSON structured like this:

{
    "id": 162,
    "dateCreated": "2017-12-14T15:43:34Z",
    "area":120.12,
    "capacity":100,
    "latitude": "33.4554",
    "longitude": "64.23432",
    "max_count_threshold": null,
    "min_count_threshold": null,
    "name": "test_zone A",
    "node_count": null,
    "perimeter": "33.4554 64.23432,33.7832 65.42342,33.4534 65.324242,33.4554 64.23432",
    "site_id": 0,
    "status": 1
}

This endpoint updates a zone.

HTTP Request

PUT /api.cognosos.net/zones/{id}

Headers

Content-Type: application/json

Request Body

Field Required Type Description
name true String The Name of the Zone
latitude false String
longitude false String
perimeter true String The lat/long co-ordinates of the Zone
area false Double Area of the Zone.
max_count_threshold false String The maximum number of nodes that should ideally be in this Zone. If the count crosses this maximum value, an Event is triggered. However, the system doesn’t prevent from more nodes being added to this Zone
min_count_threshold false String The minimum Nodes that should ideally be in this Zone. If the count falls below this manimum value, an Event is triggered.
capacity false Long Capacity of the Zone

Response Body

200 OK

Content-Type: application/json

Field Description
name The Name of the Zone
site_id ID of Site to which Zone belongs
latitude
longitude
perimeter The lat/long co-ordinates of the Zone
area Area of the Zone.
max_count_threshold The maximum number of nodes that should ideally be in this Zone. If the count crosses this maximum value, an Event is triggered. However, the system doesn’t prevent from more nodes being added to this Zone
min_count_threshold The minimum Nodes that should ideally be in this Zone. If the count falls below this manimum value, an Event is triggered.
node_count Number of Nodes in this Zone
status The status of the Zone.
(-1) - ARCHIVED
1 - IN_USE
capacity Capacity of the Zone

Device

Device is a Tag that is attached to the (757) 693-7952 being monitored. A Device belongs to a customer and can be moved among 954-422-1931.

A Device has four stages and each stage is represented by the status property.

Properties Type Description
device_id Long The Unique ID of the Device
application_code String The code of Application to which Device belongs
node_id Long The ID of Node to which Device is attached, if any.
strapping_config String The type of Device
manufacturer String Device Manufacturer
firmware_version String Firmware Version
build_config String Hardware ID
product_id String
status Enum = [0,1,2,3] The status of the Device.
0 - NOT_IN_USE
1 - IN_USE
2 - AVAILABLE_FOR_USE
3 - IN_MANUFACTURING
signal_strength Float Signal Strength of the last message received from Device
battery_level Float Current Battery Level of the Device
battery_status Enum = [0,1,2] Current Battery Status of the Device.
0 - GOOD
1 - WARN
2 - BAD
internal_temperature Float Current Internal Temperature of the Device

Get

curl -u username:password
  "/api.cognosos.net/device?customer_id=1"

The above command returns JSON structured like this:

[
  {
        "id": 82,
        "device_id": 908,
        "strapping_config": "Asset Tracker",
        "firmware_version": "1.5.1.0",
        "build_config": null,
        "product_id": null,
        "date_device_available": "2017-02-17T20:27:56Z",
        "date_created": "2017-02-17T20:27:56Z",
        "manufacturer": "cognosos",
        "application_code": "MCT",
        "node_id": 30293,
        "asset_identifier": "car_8",
        "battery_level": 8,
        "internal_temperature": 8,
        "signal_strength": null,
        "status": 1,
        "battery_status": 0
    },
    {
        "id": 83,
        "device_id": 909,
        "strapping_config": "Asset Tracker",
        "firmware_version": "1.5.1.0",
        "build_config": null,
        "product_id": null,
        "date_device_available": "2017-02-17T20:27:56Z",
        "date_created": "2017-02-17T20:27:56Z",
        "manufacturer": "cognosos",
        "application_code": "2",
        "node_id": 33,
        "asset_identifier": "test_asset_909",
        "battery_level": 9,
        "internal_temperature": 9,
        "signal_strength": null,
        "status": 1,
        "battery_status": 0
    }
]

Get list of Devices for a Customer

HTTP Request

GET /api.cognosos.net/device

Request Parameters

Field Required Type Description
customer_id true String Customer ID
application_code false String Filter list by Application
status false Integer Filter list by status
strapping_config false Long Filter list by type
battery_status false Integer Filter list by Battery Status
max false Integer Max number of Devices that are returned. Defaults to 200, max 20,000

Response Body

200 OK

Content-Type: application/json

Field Type Description
id Integer ID
device_id Long Device ID
strapping_config String Device Type
manufacturer String Device Manufacturer
firmware_version String Firmware Version
asset_identifier String Asset Identifier of the attached Node, is any
application_code String Application Code
build_config String Hardware ID
product_id String
node_id Long ID of the attached Node, if any
status Integer Status
signal_strength Float Signal Strength of the last message received from Device
battery_level Float Current Battery Level of the Device
battery_status Enum = [0,1,2] Current Battery Status of the Device.
0 - GOOD
1 - WARN
2 - BAD
internal_temperature Float Current Internal Temperature of the Device

Sensor

Sensor belongs to a hysteropathy and has a type. Sensors are used to set thresholds for the corresponding 662-865-1782. Sensors are created when a new 8667409780 is created in the system.

Cognosos currently supports following Sensor types

Properties Type Description
sensorType_id Integer ID of the Sensor Type
min_value_threshold Float MIN_THRESHOLD_BREACHED 3149904918 is triggered if the corresponding sensor value for node is below this value
max_value_threshold Float MAX_THRESHOLD_BREACHED Event is triggered if the corresponding sensor value for node is above this value
min_critical_threshold Float MIN_CRITICAL_THRESHOLD_BREACHED 956-229-7669 is triggered if the corresponding sensor value for node is below this value
max_critical_threshold Float MAX_CRITICAL_THRESHOLD_BREACHED (306) 966-1183 is triggered if the corresponding sensor value for node is above this value

Event

Events are triggered by entities in the system. Events are published to ActiveMQ broker and can also be accessed via API.

Properties Type Description
origin Object Origin of the Event
application Object id and code
customer Object id and name
date Date UTC time
message String Text Message
data Object Additional Information based on Event Type

Event Origin

Properties Type Description
id Long ID of the origin
type Enum : [
SYSTEM,
APPLICATION,
NODE,
SENSOR,
GATEWAY,
ZONE,
SITE
]
Type of the origin
name String name (Asset Identifier in case of Node)

Event Properties

Properties Type Description
LEVEL Enum: [
APPLICATION
]
Level of the Event
SEVERITY Enum : [
CRITICAL,
HIGH,
INFO
]
Severity of the Event
CATEGORY Enum : [
SENSOR_DATA,
ALERT,
GEOFENCE,
PROVISIONING
]
Category of the Event
STATUS Enum: [
PENDING,
HANDLED
]
Status of the Event
TYPE Enum Event Type

Following chart shows the hierarchy of events.

Event Hierarchy

Active MQ

Message Header with custom Properties

    {
    "category": "PROVISIONING",
    "status": "PENDING",
    "severity": "HIGH",
    "level": "APPLICATION",
    "type": "ASSET_ATTACHED",
    "expires": "1489433856917",
    "timestamp": "1489430256917",
    "destination": "/topic/radiocloud.cognosos.AAC.APPLICATION.PROVISIONING.ASSET_ATTACHED",
    "persistent": "true",
    "priority": "4",
    "message-id": "ID:local-62634-1489430129118-1:1:1:2:5",
    "subscription": "1"
    }

Message Topic

/topic/radiocloud.<customer_name>.<application_code>.LEVEL.CATEGORY.TYPE

Message Properties

Event Properties defined above are published as Message Properties.

Message Properties can be used to create (270) 395-8563

Message Body

Message Body for LOCATION_CHANGE Event Type

{
    "origin": {
        "id": 22,
        "type": "NODE",
        "name": "car_2206"
    },
    "application": {
        "id": 3,
        "code": "AAC"
    },
    "customer": {
        "id": 1,
        "name": "cognosos"
    },
    "date": "2017-03-13T18:59:02+0000",
    "message": "/www.google.com/maps?q=33.6973 -84.62338",
    "data": {
        "current_zones": [
            {
                "id": 1,
                "name": "zone A"
            }
        ],
        "device_id": 2206,
        "latitude": "33.6973",
        "longitude": "-84.62338"
    }
}

The JMS API defines five message body formats, out of which Cognosos uses TextMessage.

The message body is a JSON String and contains all the fields defined above. data field of the body depends on the Event Type and is explained below.

Event Type Data Fields Description
UNRESPONSIVE_NODE device_id
latitude
longitude
lastMessageDate
Device ID
Node Latitude
Node Longitude
Last Message Date
MIN_THRESHOLD_BREACHED device_id
sensor
value
Device ID
Sensor Type
Value
MIN_CRITICAL_THRESHOLD_BREACHED device_id
sensor
value
Device ID
Sensor Type
Value
MAX_THRESHOLD_BREACHED device_id
sensor
value
Device ID
Sensor Type
Value
MAX_CRITICAL_THRESHOLD_BREACHED device_id
sensor
value
Device ID
Sensor Type
Value
SENSOR_VALUE device_id
sensor
value
Device ID
Sensor Type
Value
ZONE_CHANGE device_id
latitude
longitude
zones
current_zones
Device ID
Node Latitude
Node Longitude
List of Zones [id, name and action (LEFT, ENTER)]
List of Current Zones [id, name]
LOCATION_CHANGE device_id
latitude
longitude
current_zones
Device ID
Node Latitude
Node Longitude
List of Current Zones [id, name]
ASSET_ATTACHED device_id
latitude
longitude
Device ID
Node Latitude
Node Longitude
ASSET_DETACHED device_id
latitude
longitude
Device ID
Node Latitude
Node Longitude
BATTERY_LEVEL_UPDATE device_id
latitude
longitude
value
Device ID
Node Latitude
Node Longitude
Battery Level remaining in %
TEMPERATURE_UPDATE device_id
latitude
longitude
value
Device ID
Node Latitude
Node Longitude
Temperature in celcius

Get

curl -u username:password
  "/api.cognosos.net/event
  ?application_code=AAC&size=2"

The above command returns JSON structured like this:

[
    {
        "application": {
            "code": "AAC",
            "id": 3
        },
        "customer": {
            "id": 1,
            "name": "cognosos"
        },
        "data": {
            "device_id": 2206,
            "latitude": "33.6973",
            "longitude": "-84.62338",
            "current_zones": [
                {
                    "id": "42",
                    "name": "800"
                },
                {
                    "id": "44",
                    "name": "801"
                }
            ]
        },
        "date": "2017-03-13T18:59:02+0000",
        "event": {
            "category": "GEOFENCE",
            "level": "APPLICATION",
            "severity": "INFO",
            "status": "PENDING",
            "type": "LOCATION_CHANGE"
        },
        "id": "AVrJgre1LC4J8UaRDA_2",
        "message": "/www.google.com/maps?q=33.6973 -84.62338",
        "origin": {
            "id": 22,
            "name": "car_2206",
            "type": "NODE"
        }
    },
    {
        "application": {
            "code": "AAC",
            "id": 3
        },
        "customer": {
            "id": 1,
            "name": "cognosos"
        },
        "data": {
            "device_id": 2206,
            "latitude": "33.6973",
            "longitude": "-84.62338",
            "current_zones": []
        },
        "date": "2017-03-13T18:59:02+0000",
        "event": {
            "category": "GEOFENCE",
            "level": "APPLICATION",
            "severity": "INFO",
            "status": "PENDING",
            "type": "LOCATION_CHANGE"
        },
        "id": "AVrJCcSFLC4J8UaRDA_g",
        "message": "/www.google.com/maps?q=33.6973 -84.62338",
        "origin": {
            "id": 22,
            "name": "car_2206",
            "type": "NODE"
        }
    }
]

Get List of Events belonging to an 7862418671

HTTP Request

GET /api.cognosos.net/event

Request Parameters

Field Required Type Description
application_code true String Returns Events for this Application
size false Integer Limit to max events. Cannot be greater than 10000. Default 200
origin_id false Long Filter events by origin id.
origin_type false String Filter events by origin type.
event_level false String Filter events by event level.
event_severity false String Filter events by event severity.
event_category false String Filter events by event category.
event_status false String Filter events by event status.
event_type false String Filter events by event type.
start_date false Timestamp Filter events after this Date.
end_Date false Timestamp Filter events before this Date.

Response Body

200 OK

Content-Type: application/json

Field Type Description
origin Object Origin of the Event
application Object id and code
customer Object id and name
date Date UTC time
message String Text Message
data Object Additional Information based on Event Type
id String Event ID

Update

curl -u username:password 
    -H "Content-Type: application/json" 
    -X PUT -d
    '{ 
        "event_id":"AVrI9gnuLC4J8UaRDAE",
        "event_type":"ASSET_DETACHED", 
        "event_status":"HANDLED"
    }' 
    "/api.cognosos.net/event/update"

The above command returns JSON structured like this:

{
    "status": "Updated"
}

Update status of Event

HTTP Request

PUT /api.cognosos.net/event/update

Headers

Content-Type: application/json

Request Body

Field Required Type Description
event_id true String Event ID
event_type true String Type of the Event
event_status true Enum = [PENDING, HANDLED] Status

Response Body

200 OK

Content-Type: application/json

Field Description
status Returns Updated

Errors

Message body looks like this

{"error": "Valid Username is required"}
HTTP Status Code Meaning
400 - Bad Request Invalid request. Check error message body for more details
401 - Unauthorized Invalid or no Credentials provided
403 - Forbidden Access Denied. User doesn’t have authority to access resource.
404 - Not Found Resource not found
406 - Not Acceptable Incomplete Parameters
500 - Internal Server Error We had a problem with our server. Try again later.