Example requests

All sensors

https://api.modio.se/v0

Response to GET request:

{
  "name": "Box_cdef",
  "host": "d0ff50abcdef",
  "lastclock": 1416586606,
  "items": [
    {
      "name": "pump 3.40004 BT1 Outdoor temp",
      "unit": "degC",
      "key": "modbus.pump.F1345.3.40004",
      "configurable": false
    },
    {
      "name": "pump 3.47024 Own Curve P3",
      "unit": "degC",
      "config": {
        "audit": [],
        "target": null,
        "lastclock": null,
        "expected": null
      },
      "key": "modbus.pump.F1345.3.47024",
      "configurable": true
    }
  ],
  "ip": "10.0.0.1"
}

A sensors last value

https://api.modio.se/v0/d0ff50abcdef/modbus.pump.F1345.3.40004

Response to GET request:

{
  "name": "pump 3.40004 BT1 Outdoor temp",
  "unit": "degC",
  "lastclock": 1416586545,
  "lastvalue": 2.4,
  "key": "modbus.pump.F1345.3.40004",
  "configurable": false
}

Note how this request always includes lastclock/lastvalue

Latest history

https://api.modio.se/v0/d0ff50abcdef/modbus.pump.F1345.3.40004/history

Response to GET request:

[
  [1416586545, 2.4],
  [1416586847, 2.8]
]

History for a specific period

Assuming that the time is 2014-11-21 16:17:45 UTC and we want data for the latest hour, we make a GET request for:

https://api.modio.se/v0/d0ff50abcdef/modbus.pump.F1345.3.40004/history/1416583065/1416586665

In this case we will be redirected to:

https://api.modio.se/v0/d0ff50abcdef/modbus.pump.F1345.3.40004/history/1416582900/1416586500

The new time span is from 15:15:00 to 16:15:00. The response contains:

[
  [1416582945, 2.4],
  [1416583245, 2.4],
  [1416583545, 2.4],
  [1416583965, 2.4],
  [1416584265, 2.4],
  [1416584566, 2.4],
  [1416584865, 2.5],
  [1416585165, 2.5],
  [1416585585, 2.4],
  [1416585885, 2.3],
  [1416586185, 2.3],
  [1416586485, 2.3]
]

Note that the first value is before the originally requested time span, and that an additional request will be needed to check for any remaining values after 16:15.

History lookup preparation calculation

For convenience you can use the history_prepare method to take an arbitary time-range and calculate the URI’s needed to get all the data in the range start/stop.

Requesting the range 2015-12-31 02:22:44 UTC to 2016-01-11 16:09:24 UTC:

https://api.modio.se/v0/d0ff50abcdef/modbus.pump.F1345.3.40004/history_prepare/1351441166/1452528564

Which will return an array of chunked requests that will properly fulfill the original request, in order of time-range.

[
  "/v0/d0ff50abcdef/modbus.pump.F1345.3.40004/history/1451520000/1452470400",
  "/v0/d0ff50abcdef/modbus.pump.F1345.3.40004/history/1452470400/1452528000",
  "/v0/d0ff50abcdef/modbus.pump.F1345.3.40004/history/1452525300/1452528900"
]

Thus resulting in the following periods:

  • 2015-12-31 00:00:00 UTC to 2016-01-11 00:00:00 UTC
  • 2016-01-11 00:00:00 UTC to 2016-01-11 16:00:00 UTC
  • 2016-01-11 15:15:00 UTC to 2016-01-11 16:15:00 UTC

Note the overlap on the second to last request, as the system slices data in periods of 60 minutes. This system has been chosen to guarantee cacheability.

Triggers and Trigger Events

A trigger may involved zero or more items, and may also involve one or more hosts. Thus, the same trigger may be listed under several hosts, and several sensors.

This is because a trigger may represent a rather complex state, such as:

host ff00ff00ffee offline - and host ff00ff00ffee reports a temperature difference between outside and inside of more than 20 degrees C.

Note that in most cases, triggers are not this complex, and the example above is contrived, but serves to make a point.

Triggers

https://api.modio.se/v0/trigger

Response to the GET request for all triggers

[
  {
    "triggerid": 1719,
    "description": "Frost alarm",
    "hosts": ['d0ff50abcdef'],
    "lastchange": 1421944072,
    "value": "OK", 
    "severity": [5, "A-Larm"]
  },
  {
    ...
  }
]

Get all triggers for one host:

https://api.modio.se/v0/d0ff50abcdef/trigger

Get all triggers for one single item:

https://api.modio.se/v0/d0ff50abcdef/modbus.pump.F1345.3.40004/trigger

Get the details of this one single trigger:

https://api.modio.se/v0/trigger/1719

Events from triggers

The events are formatted as Alarm Events

Get the last events from this trigger:

https://api.modio.se/v0/trigger/1719/events

Get a list of (if any) events during the time range between start and stop:

https://api.modio.se/v0/trigger/1719/events/1351441166/1452528564