Back to top

LX IoT Core Event Pull APIs

The LX IoT Core Cloud provides two mechanisms for getting events that are submitted from devices.

  1. LX IoT Core Coud pushes the data into the third party system. This is typically done using a HTTP POST.

  2. Data is retrieved using LX IoT Core cloud APIs on request by the third party system.

This document covers method 2.

Authentication


In order to retrieve events HTTP requests must be authenticated. This is done by including an API key (supplied on request from LX) in the http Authorization header.

For example if the API key supplied is cDD1Juz2k1G3ZpToHprX80BD it would be included as follows:

Authorization: token cDD1Juz2k1G3ZpToHprX80BD

If the token is either missing or invalid you will receive a 401 status code for any request made to the APIs listed in this document.

Events

When pulling events you can choose whether to get events from a specific base station or from all base stations.

Paging

Events are returned in batches of events. The default is 100 events per batch.

The events are designed to be treated as a stream. By saving the position you were up to in the stream you can pull only events you haven’t received before.

Your first read should use 0 as the position value, which will start you at the beginning.

NOTE: While the position is an integer number it doesn’t relate to the number of events being returned or the size of the events on disk. Your code should not try to make sense of what it is, just use it to remember where you were up to.

Each request includes a link in the response to fetch the next batch of events. This link will include the position information, so you can also just save the link and use it next time you would like to pull newer data.

Here is an example of the response you’ll receive when you reach the end of the stream.

{
  "organisation": "cropmanager",
  "project": "cumulus",
  "events": [],
  "_links": { //_
    "self": {
      "href": "/v0/orgs/cropmanager/projects/cumulus/events?position=82574&pageSize=0"
    },
    "next-page": {
      "href": "/v0/orgs/cropmanager/projects/cumulus/events?position=82574",
      "title": "Get the next page of events"
    }
  }
}
  • organisation is the organisation these events belong to.

  • project is the project within the organisation the events are grouped under.

  • events is an array which contains the events as JSON objects. If you receive less than the number of events you requested (the default is 100) it means you are at the end of the stream.

  • _links contains links to other API functions.

    • self contains a URL that can load this exact same set of events again. In this example it wouldn’t load any events as none were returned. This is mostly useful if you need give someone a link to where you received some data of interest as it allows them to quickly find what you saw.
    • next-page contains the URL that should be used to get the next page of events. Use the href field.

Polling Frequency

There is currently no rate limit on how frequently you can poll for new events. However please do not poll for sustained periods any more frequently than once per minute.

Given the frequency data is being collected for this project anything more frequent than once per minute is unlikely to be helpful anyway.

Special Position Values

📖  Quite often while doing testing or diagnostics it is helpful to quickly retrieve a handful of recent events. Rather than starting at position 0 or guessing a random position and working towards the end of the stream, which can be quite time consuming a convenient method of retrieving the last n events is provided.

To retrieve the last n events simply use -n as the position. For example to fetch the last 5 events make the request with position=-5.

Please note when using this approach that events will still be returned in batches as determined by the page size.

All Base Stations

All Base Station Event Batch
GET/v0/orgs/cropmanager/projects/cumulus/events?position={position}&pageSize={pageSize}

Example URI

GET https://api.iotcores.com/v0/v0/orgs/cropmanager/projects/cumulus/events?position=0&pageSize=100
URI Parameters
HideShow
position
number (required) Example: 0

The position where reading should start. Initially use 0, but later on use the value provided in the next-page link’s href.

pageSize
number (optional) Example: 100

The maximum number of events to retrieve. Generally we recommend sticking to the default which is 100 events.

Response  200
HideShow
Headers
Content-Type: application/hal+json
Body
{
  "organisation": "cropmanager",
  "project": "cumulus",
  "events": [
    {
      "eventId": "0000000000014291",
      "$received": "2016-08-03T06:17:45.5009357+00:00",
      "$deviceId": "3138323834345117005E002B",
      "broadcast": {
        "sensorBlock": {
          "sensorUID": 13114764689391223000,
          "sensorUIDHex": "b601010000000015",
          "packetId": 372,
          "sensorTemperature_dC": 219,
          "batteryOkay": true,
          "sensorVersion_word": 16779521
        },
        "baseBlock": {
          "loraRSSI_dBm": -86,
          "baseUID": 13115046164367933000,
          "baseUIDHex": "b602010000000017",
          "baseTemperature_dC": 250,
          "baseVersion": "1.0.0.0"
        },
        "timestamp": "2016-08-03T06:17:45.5009357+00:00"
      }
    },
    {
      "eventId": "0000000000014293",
      "$received": "2016-08-03T06:18:15.1587713+00:00",
      "$deviceId": "3138323834345117005E002B",
      "broadcast": {
        "sensorBlock": {
          "sensorUID": 13114764689391223000,
          "sensorUIDHex": "b601010000000021",
          "packetId": 371,
          "sensorTemperature_dC": 222,
          "batteryOkay": true,
          "probeData": {
            "serialNumber": "S0000207203",
            "sensorReading": [
              {
                "temperature_raw": 158,
                "moisture_raw": 158875
              },
              {
                "temperature_raw": 144,
                "moisture_raw": 172250
              },
              {
                "temperature_raw": 148,
                "moisture_raw": 184781
              },
              {
                "temperature_raw": 150,
                "moisture_raw": 185343
              },
              {
                "temperature_raw": 160,
                "moisture_raw": 240937
              },
              {
                "temperature_raw": 164,
                "moisture_raw": 373656
              }
            ]
          },
          "sensorVersion_word": 16779777
        },
        "baseBlock": {
          "loraRSSI_dBm": -91,
          "baseUID": 13115046164367933000,
          "baseUIDHex": "b602010000000017",
          "baseTemperature_dC": 250,
          "cellularRSSI_dBm": -103,
          "cellularBER": 37,
          "baseVersion": "1.0.0.0"
        },
        "timestamp": "2016-08-03T06:18:15.1587713+00:00"
      }
    },
    {
      "eventId": "00000000000142c0",
      "$received": "2016-08-03T06:35:44.1478943+00:00",
      "$deviceId": "31383238343451170046002C",
      "broadcast": {
        "sensorBlock": {
          "sensorUID": 13114764689391223000,
          "sensorUIDHex": "b601010000000018",
          "packetId": 267,
          "sensorTemperature_dC": 173,
          "batteryOkay": true,
          "probeData": {
            "serialNumber": "S0000202685",
            "sensorReading": [
              {
                "temperature_raw": 126,
                "moisture_raw": 592621
              },
              {
                "temperature_raw": 120,
                "moisture_raw": 523414
              },
              {
                "temperature_raw": 120,
                "moisture_raw": 276707
              },
              {
                "temperature_raw": 130,
                "moisture_raw": 295823
              },
              {
                "temperature_raw": 140,
                "moisture_raw": 427865
              },
              {
                "temperature_raw": 146,
                "moisture_raw": 547896
              }
            ]
          },
          "sensorVersion_word": 16779777
        },
        "baseBlock": {
          "loraRSSI_dBm": -95,
          "baseUID": 13115046164367933000,
          "baseUIDHex": "b602010000000016",
          "baseTemperature_dC": 250,
          "baseVersion": "0.0.1.3"
        },
        "timestamp": "2016-08-03T06:35:44.1478943+00:00"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "/v0/orgs/cropmanager/projects/cumulus/events?position=82574&pageSize=3"
    },
    "next-page": {
      "href": "/v0/orgs/cropmanager/projects/cumulus/events?position=82624",
      "title": "Get the next page of events"
    }
  }
}

Specific Base Station

Specific Base Station Event Batch
GET/v0/orgs/cropmanager/projects/cumulus/devices/{deviceId}/events?position={position}&pageSize={pageSize}]

Example URI

GET https://api.iotcores.com/v0/v0/orgs/cropmanager/projects/cumulus/devices/3138323834345117005E002B/events?position=0&pageSize=100]
URI Parameters
HideShow
deviceId
string (required) Example: 3138323834345117005E002B

The serial number of the base station to fetch events from.

position
number (required) Example: 0

The position where reading should start. Initially use 0, but later on use the value provided in the next-page link’s href.

pageSize
number (optional) Example: 100

The maximum number of events to retrieve. Generally we recommend sticking to the default which is 100 events.

Response  200
HideShow
Headers
Content-Type: application/hal+json
Body
{
  "organisation": "cropmanager",
  "project": "cumulus",
  "events": [
    {
      "eventId": "0000000000014291",
      "$received": "2016-08-03T06:17:45.5009357+00:00",
      "$deviceId": "3138323834345117005E002B",
      "broadcast": {
        "sensorBlock": {
          "sensorUID": 13114764689391223000,
          "sensorUIDHex": "b601010000000015",
          "packetId": 372,
          "sensorTemperature_dC": 219,
          "batteryOkay": true,
          "sensorVersion_word": 16779521
        },
        "baseBlock": {
          "loraRSSI_dBm": -86,
          "baseUID": 13115046164367933000,
          "baseUIDHex": "b602010000000017",
          "baseTemperature_dC": 250,
          "baseVersion": "1.0.0.0"
        },
        "timestamp": "2016-08-03T06:17:45.5009357+00:00"
      }
    },
    {
      "eventId": "0000000000014293",
      "$received": "2016-08-03T06:18:15.1587713+00:00",
      "$deviceId": "3138323834345117005E002B",
      "broadcast": {
        "sensorBlock": {
          "sensorUID": 13114764689391223000,
          "sensorUIDHex": "b601010000000021",
          "packetId": 371,
          "sensorTemperature_dC": 222,
          "batteryOkay": true,
          "probeData": {
            "serialNumber": "S0000207203",
            "sensorReading": [
              {
                "temperature_raw": 158,
                "moisture_raw": 158875
              },
              {
                "temperature_raw": 144,
                "moisture_raw": 172250
              },
              {
                "temperature_raw": 148,
                "moisture_raw": 184781
              },
              {
                "temperature_raw": 150,
                "moisture_raw": 185343
              },
              {
                "temperature_raw": 160,
                "moisture_raw": 240937
              },
              {
                "temperature_raw": 164,
                "moisture_raw": 373656
              }
            ]
          },
          "sensorVersion_word": 16779777
        },
        "baseBlock": {
          "loraRSSI_dBm": -91,
          "baseUID": 13115046164367933000,
          "baseUIDHex": "b602010000000017",
          "baseTemperature_dC": 250,
          "cellularRSSI_dBm": -103,
          "cellularBER": 37,
          "baseVersion": "1.0.0.0"
        },
        "timestamp": "2016-08-03T06:18:15.1587713+00:00"
      }
    }
  ],
  "_links": {
    "self": {
      "href": "/v0/orgs/cropmanager/projects/cumulus/devices/3138323834345117005E002B/events?position=82862&pageSize=2"
    },
    "next-page": {
      "href": "/v0/orgs/cropmanager/projects/cumulus/devices/3138323834345117005E002B/events?position=8301",
      "title": "Get the next page of events"
    }
  }
}

Generated by aglio on 22 May 2017