Rate this page

★
★
★
★
★
★
★
★
★
★

Event API

The Notehub event API provides RESTful methods that can be used to GET event data.

note

Most event APIs are available in the context of both Notehub projects and ProductUIDs. Except for Get Events by Project, this document shows the ProductUID context only. You can substitute in projects for products and projectUID for productUID for the other APIs listed.

Get Events by Project

Get an array of Notehub events by ProjectUID.

Minimum Notehub project-level role required:

Arguments

`baseURL`

string

The Notehub API endpoint URL. For example: https://api.notefile.net/v1.

`projectUID`

string

The ProjectUID of a Notehub project.

`authToken`

string

A Notehub API authentication token.


curl -X GET
     -L '[baseURL]/projects/{projectUID}/events'
     -H 'X-SESSION-TOKEN: [authToken]'

Response Members

`uid`

string

The globally-unique identifier of the event.

`device_uid`

string

The globally-unique identifier of the device.

`file`

string

The name of the Notefile.

`captured`

string

The date and time this event was captured by the device.

`received`

string

The date and time this event was received by Notehub.

`body`

object

A JSON object containing the event details.

`tower_location`

object

An object containing information about the physical location of the cell tower used to receive the event.

`gps_location`

object

An object containing information about the physical location of the device that sent the event based on GPS coordinates.

`through`

string

The globally-unique identifier of the last event in the array.

`has_more`

boolean

Defines whether or not there are additional events beyond this list.

Example Response


{
   "events":[
      {
         "uid":"00000000-0000-0000-0000-000000000000",
         "device_uid":"dev:000000000000000",
         "file":"data.qo",
         "captured":"2021-04-26T19:13:46Z",
         "received":"2021-04-26T19:13:46Z",
         "body":{
            "temperature":54.3
         },
         "tower_location":{
            "when":"2021-04-26T19:13:46Z",
            "name":"Shorewood Hills WI",
            "country":"US",
            "timezone":"America/Chicago",
            "latitude":43.073787499999995,
            "longitude":-89.44367187499999
         },
          "gps_location":{
            "same properties as tower_location"
          },
      }
   ],
   "through":"00000000-0000-0000-0000-000000000000",
   "has_more":false
}

Get Latest Events

Get the most recent health log, session, and note events by ProductUID and DeviceUID.

Minimum Notehub project-level role required:

Arguments

`baseURL`

string

The Notehub API endpoint URL. For example: https://api.notefile.net/v1.

`productUID`

string

The ProductUID from a Notehub project.

`deviceUID`

string

The DeviceUID of a Notehub device.

`authToken`

string

A Notehub API authentication token.


curl -X GET
     -L '[baseURL]/products/{productUID}/devices/{deviceUID}/latest'
     -H 'X-SESSION-TOKEN: [authToken]'

Response Members

`file`

string

The name of the Notefile.

`captured`

string

The date and time this event was captured by the device.

`received`

string

The date and time this event was received by Notehub.

`event_uid`

string

The globally unique identifier of the event.

`body`

object

A JSON object containing the event details.

Example Response


{
  "latest_events": [
    {
      "file": "_health.qo",
      "captured": "2021-04-27T15:37:47Z",
      "received": "2021-04-27T15:37:58Z",
      "event_uid": "00000000-0000-0000-0000-000000000000",
      "body": {
        "text": "boot (brown-out \u0026 hard reset [12460])"
      }
    },
    {
      "file": "_session.qo",
      "captured": "2021-04-27T15:37:55Z",
      "received": "2021-04-27T15:37:55Z",
      "event_uid": "00000000-0000-0000-0000-000000000000",
      "body": {
        "why": "first sync, continuous connection mode (TLS)"
      }
    },
    {
      "file": "data.qo",
      "captured": "2021-04-26T19:13:23Z",
      "received": "2021-04-26T19:13:49Z",
      "event_uid": "00000000-0000-0000-0000-000000000000",
      "body": {
        "temperature": 54.3
      }
    }
  ]
}

Get Health Log

Get an array of health log events by ProductUID and DeviceUID.

Minimum Notehub project-level role required:

Arguments

`baseURL`

string

The Notehub API endpoint URL. For example: https://api.notefile.net/v1.

`productUID`

string

The ProductUID from a Notehub project.

`deviceUID`

string

The DeviceUID of a Notehub device.

`authToken`

string

A Notehub API authentication token.


curl -X GET
     -L '[baseURL]/products/{productUID}/devices/{deviceUID}/health-log'
     -H 'X-SESSION-TOKEN: [authToken]'

Response Members

`when`

string

The date and time this event was received by Notehub.

`alert`

boolean

The date and time this event was received by Notehub.

`text`

string

Descriptive information about the health log event.

Example Response


{
  "health_log": [
    {
      "when": "2021-04-27T15:37:47Z",
      "alert": false,
      "text": "boot (brown-out \u0026 hard reset [12460])"
    }
  ]
}

Get Sessions

Get all session events by ProductUID and DeviceUID.

Minimum Notehub project-level role required:

Arguments

`baseURL`

string

The Notehub API endpoint URL. For example: https://api.notefile.net/v1.

`productUID`

string

The ProductUID from a Notehub project.

`deviceUID`

string

The DeviceUID of a Notehub device.

`authToken`

string

A Notehub API authentication token.


curl -X GET
     -L '[baseURL]/products/{productUID}/devices/{deviceUID}/sessions'
     -H 'X-SESSION-TOKEN: [authToken]'

Response Members

`session`

string

The globally-unique identifier of the event.

`device`

string

The globally-unique identifier of the device.

`product`

string

The globally-unique identifer of the product.

`fleet`

string

The globally-unique identifier of the fleet.

`addr`

string

The internal IP address of the Notehub.io network handler.

`cell`

string

A comma-separated list of MCC, MNC, LAC, and Cell ID data (see below).

`triangulation_occurred`

boolean

Whether or not cell tower triangulation occurred as part of this event.

`rssi`

int

Received Signal Strength Indicator. It is an estimated measure of power level that an RF client device is receiving from an access point or router.

`sinr`

int

Signal-to-interference-plus-noise ratio, defined as the power of a signal of interest divided by the sum of the interference power and the power of the background noise.

`rsrp`

int

Reference Signal Received Power is the power of the LTE Reference Signals spread over the full bandwidth and narrow band.

`rsrq`

int

Reference Signal Received Quality indicates the quality of the received reference signal. The RSRQ measurement provides additional information when RSRP is not sufficient to make a reliable handover or cell reselection decision.

`rat`

string

The type of Radio Access Technology used.

`tower.time`

UNIX Epoch time

The time the network session was established.

`tower.n`

string

The location of the cell tower.

`tower.c`

string

The two-digit country code of the cell tower.

`tower.lat`

decimal

The latitude of the cell tower.

`tower.lon`

decimal

The longitude of the cell tower.

`tower.zone`

string

The timezone of the cell tower.

`tower.mcc`

int

The mobile country code of the cell tower. For example, in the United States it is 310.

`tower.mnc`

int

The mobile network code of the cell tower, which identifies the mobile operator.

`tower.lac`

int

The location area code of the cell tower, which is a unique identifer of the current location area.

`tower.cid`

int

The Cell ID or CID of the cell tower. This is a unique number used to identify each Base Transceiver Station (BTS) or sector of a BTS within a location area code.

`tower.l`

string

The Google Maps Plus Code for the cell tower.

`tower.count`

int

Number of times the device has recently accessed this cell tower.

`tower.towers`

int

Number of distinct cell towers accessed in this session (if using continuous mode).

`session_log_key`

string

The unique key for this session, comprised of the Device UID and timestamp.

`this` `next` `period`

object

Contains detailed device usage information. this = lifetime usage, reported at the beginning of a session. next = resolves difference between usage sent at the beginning of a new session and the beginning of the next session. period = usage during the current session.

`voltage`

decimal

The measure of voltage from the onboard voltage monitor.

`temp`

decimal

The measure of temperature in celsius from the onboard temperature sensor.

`continuous`

boolean

Whether or not the device was in continuous mode in this session.

`tls`

boolean

Whether or not the session data was sent with TLS enabled.

`work`

UNIX Epoch time

Tracks when work was last done for this session.

`events`

int

The number of events transferred in this session.

`moved`

UNIX Epoch time

Tracks the last time the device experienced motion.

`orientation`

string

The orientation of the device during the session.

`trigger`

string

The reason this session was created and sent to Notehub.

`more_pages`

boolean

Whether or not there are additional sessions to display.

Example Response


{
  "sessions": [
    {
      "session": "00000000-0000-0000-0000-000000000000",
      "device": "dev:000000000000000",
      "product": "product:com.your-company.your-name:project",
      "fleet": "fleet:00000000-0000-0000-0000-000000000000",
      "addr": "tcps:20029:0.0.0.0",
      "cell": "310,410,12345,12345678",
      "triangulation_occurred": false,
      "rssi": -55,
      "sinr": 183,
      "rsrp": -82,
      "rsrq": -13,
      "rat": "emtc",
      "tower": {
        "time": 1619537875,
        "n": "Shorewood Hills WI",
        "c": "US",
        "lat": 43.073787499999995,
        "lon": -89.44367187499999,
        "zone": "America/Chicago",
        "mcc": 310,
        "mnc": 410,
        "lac": 12345,
        "cid": 12345678,
        "l": "86MG3HF4+GG8",
        "count": 2,
        "towers": 1
      },
      "session_log_key": "dev:000000000000000/2021-04-27T15:37:55.619Z",
      "this": {
        "since": 1616256786,
        "bytes_rcvd": 827688,
        "bytes_sent": 268919,
        "sessions_tcp": 88,
        "sessions_tls": 60,
        "notes_rcvd": 38,
        "notes_sent": 302
      },
      "next": {},
      "period": {
        "since": 1619537873,
        "duration": 8,
        "bytes_rcvd": 1611,
        "bytes_sent": 2023,
        "sessions_tls": 1,
        "notes_sent": 5
      },
      "voltage": 4.98,
      "temp": 19.87,
      "continuous": true,
      "tls": true,
      "work": 1619537880,
      "events": 5,
      "moved": 1619537874,
      "orientation": "landscape-right",
      "trigger": "first sync, continuous connection mode"
    }
  ],
  "more_pages": false
}

Environment Variable API Product API

Event API

Get Events by Project

baseURL

projectUID

authToken

uid

device_uid

file

captured

received

body

tower_location

gps_location

through

has_more

Get Latest Events

baseURL

productUID

deviceUID

authToken

file

captured

received

event_uid

body

Get Health Log

baseURL

productUID

deviceUID

authToken

when

alert

text

Get Sessions

baseURL

productUID

deviceUID

authToken

session

device

product

fleet

addr

cell

triangulation_occurred

rssi

sinr

rsrp

rsrq

rat

tower.time

tower.n

tower.c

tower.lat

tower.lon

tower.zone

tower.mcc

tower.mnc

tower.lac

tower.cid

tower.l

tower.count

tower.towers

session_log_key

this next period

voltage

temp

continuous

tls

work

events

moved

orientation

trigger

more_pages

`baseURL`

`projectUID`

`authToken`

`uid`

`device_uid`

`file`

`captured`

`received`

`body`

`tower_location`

`gps_location`

`through`

`has_more`

`baseURL`

`productUID`

`deviceUID`

`authToken`

`file`

`captured`

`received`

`event_uid`

`body`

`baseURL`

`productUID`

`deviceUID`

`authToken`

`when`

`alert`

`text`

`baseURL`

`productUID`

`deviceUID`

`authToken`

`session`

`device`

`product`

`fleet`

`addr`

`cell`

`triangulation_occurred`

`rssi`

`sinr`

`rsrp`

`rsrq`

`rat`

`tower.time`

`tower.n`

`tower.c`

`tower.lat`

`tower.lon`

`tower.zone`

`tower.mcc`

`tower.mnc`

`tower.lac`

`tower.cid`

`tower.l`

`tower.count`

`tower.towers`

`session_log_key`

`this` `next` `period`

`voltage`

`temp`

`continuous`

`tls`

`work`

`events`

`moved`

`orientation`

`trigger`

`more_pages`