Logging sensor records with the API

Before submitting records you'll need to generate an access token (see Authenticating with Oauth2).

URL

https://io.trap.nz/api-sensor/iot/sensor-record

Method

POST

URL Params

_format=format

The format you wish to return your data in. If you leave this blank, the server will return its default.

Valid options are:
* hal_json
* json
* xml

Headers

key value
Content-Type application/hal+json
Authorization bearer [access_token]
Accept application/hal+json
X-CSRFToken Optional, depending on connection method, this is unlikely to be required. Use results of https://api.trap.nz/session/token

Data Params

key value Required Notes Json
dev_id string Yes The id of the device "trap-example-001"

Data Params: metadata

key value Required Notes Json
time Date Yes Date is in ISO 8601, if no timezone is included the date will be parsed by the current server time (e.g NZST and NZDT). [{"value": "2020-07-21T18:11:11"}] or if the time is in UTC [{"value": "2020-07-21T18:11:11Z"}] or NZST [{"value": "2020-07-21T18:11:11+12:00"}]

Data Params: metadata: gateways

key value Required Notes Json
field_rssi integer No Relative received signal strength [{"value": 5}]
field_snr decimal No Signal to noise ratio [{"value": 1.6}]

Data Params: payload_fields

key value Required Notes Json
type string Yes Must be "sensor_report" [{"target_id":"sensor_report"}]
field_event string Yes accepted values: Sprung, Set, Vibration, Heartbeat, Baitlevel [{"value": "Vibration"}]
field_status string No accepted values: Sprung, Set, Baitlevel [{"value": "Set"}]
field_network string No Network name [{"value": "Spark"}]
field_gateway string No Mac address of the receiving gateway [{"value": "0A:2B:4C:6D:8E:9F"}]
field_sequence integer No Sequence number from the node [{"value": 3}]
field_counter integer No Number of strikes recorded [{"value": 1}]
field_battery_voltage decimal No Battery voltage [{"value": 1.4}]
field_tilt_sensor string No accepted values: True, False, Fail, NotInstalled [{"value": "True"}]
field_timeout integer No Heartbeat timeout in seconds, accepted values: -1 (no heart beat) , 0 (expired), 1+ (heatbeat in seconds). Defaults to 86400 if not set [{"value": 20}]

Example:

{
    "dev_id": "example-0010",
    "metadata": {
      "time": "2018-05-11T10:00:00",
      "gateways": [{
          "rssi": 3,
          "snr": 1.4
        }]
    },
    "payload_fields": {
      "type": [{ "target_id": "sensor_report" }],
      "field_event": [{ "value": "Vibration" }],
      "field_status": [{ "value": "Set" }],
      "field_network": [{"value": "Spark"}],
      "field_gateway": [{"value": "0A:2B:4C:6D:8E:9F"}],
      "field_sequence": [{"value": 3}],
      "field_counter": [{"value": 1}],
      "field_battery_voltage": [{ "value": 1.2 }],
      "field_tilt_sensor": [{"value": "True"}],
      "field_timeout": [{"value":10}]
    }
}

Or for Baitstation levels:

{
    "dev_id": "bs-example-001",
    "metadata": {
      "time": "2018-05-11T10:00:00",
      "gateways": [{
          "rssi": 3,
          "snr": 1.4
        }]
    },
    "payload_fields": {
      "type": [{ "target_id": "sensor_report" }],
      "field_event":[{"value":"Baitlevel"}],
      "field_status":[{"value":"Baitlevel"}],
      "field_battery_voltage":[{"value":1.2}],
      "field_data":[{"value":3.5}]
    }
}

Success Response

On success, the processed content will be returned as json, including all system meta data.

The example is a semi-truncated example of the above record submission

Code: 201 CREATED

{
  "nid": [{ "value": 12213949 }],
  "uuid": [{ "value": "c52a6200-d10f-44ec-8dcf-9f0e0ed34015" }],
  "vid": [{ "value": 12214030 }],
  "langcode": [{ "value": "en" }],
  "type": [{
    "target_id": "sensor_report",
    "target_type": "node_type",
    "target_uuid": "2baee925-90a6-48e9-a9a8-7fd5c831879e"
  }],
  "revision_timestamp": [{
    "value": "2021-06-08T05:44:15+00:00",
    "format": "Y-m-d\\TH:i:sP"
  }],
  "revision_uid": [{
    "target_id": 5,
    "target_type": "user",
    "target_uuid": "5838624f-b4ff-4ee0-b7e6-fd2ec59b0b6b",
    "url": "\/user\/5"
  }],
  "revision_log": [],
  "status": [{ "value": true }],
  "uid": [{
    "target_id": 5,
    "target_type": "user",
    "target_uuid": "5838624f-b4ff-4ee0-b7e6-fd2ec59b0b6b",
    "url": "\/user\/5"
  }],
  "title": [{ "value": "motiv: example-0010 (2018-05-11T10:00:00)" }],
  "created": [{
    "value": "2021-06-08T05:44:15+00:00",
    "format": "Y-m-d\\TH:i:sP"
  }],
  "changed": [{
    "value": "2021-06-08T05:44:15+00:00",
    "format": "Y-m-d\\TH:i:sP"
  }],
  "promote": [{ "value": false }],
  "sticky": [{ "value": false }],
  "default_langcode": [{ "value": true }],
  "revision_translation_affected": [{ "value": true }],
  "path": [{
    "alias": null,
    "pid": null,
    "langcode": "en"
  }],
  "field_battery_voltage": [{ "value": "1.2" }],
  "field_counter": [{ "value": 1 }],
  "field_data": [],
  "field_date": [{ "value": "2018-05-11T22:00:00+12:00" }],
  "field_event": [{ "value": "Vibration" }],
  "field_gateway": [{ "value": "0A:2B:4C:6D:8E:9F" }],
  "field_location": [],
  "field_network": [{ "value": "Spark" }],
  "field_rssi": [{ "value": 3 }],
  "field_sensor_id": [{ "value": "example-0010" }],
  "field_sequence": [{ "value": 3 }],
  "field_snr": [{ "value": "1.4" }],
  "field_status": [{ "value": "Set" }],
  "field_tilt_sensor": [{ "value": "True" }],
  "field_timeout": [{ "value": 10 }]
}

Error Response

This is a sample of the most likely errors you are likely to encounter.

Code: 403 Forbidden

{ message : "You are not authorized to create this node entity of bundle regions." }

Your access token is either not set or it has expired.

Code: 406 UNPROCESSABLE ENTITY

{ message : "Email Invalid" }

406 typically signifies an indicated field is missing, or the json is incorrect

Code: 422 Unprocessable Entity

{ message : "Type https:\/\/[HOST]\/rest\/type\/node\/[TYPE] does not correspond to an entity on this site" }

Your json is likely malformed. Another common cause is the _links type href being incorrect, such as using http instead of https.

Sample Call

Use curl to create a sensor record using the example data above:

curl -X POST \
  'https://io.trap.nz/api-sensor/iot/sensor-record?_format=json' \
  -H 'Authorization: Bearer ************' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/hal+json' \
  -H 'accept: application/hal+json' \
  -d '{
    "dev_id": "trap-example-001",
    "metadata": {
      "time": "2020-05-11T10:00:00",
      "gateways": [{
          "rssi": 3,
          "snr": 1.4
        }]
    },
    "payload_fields": {
      "type": [{ "target_id": "sensor_report" }],
      "field_event": [{ "value": "Vibration" }],
      "field_status": [{ "value": "Set" }],
      "field_network": [{"value": "Spark"}],
      "field_gateway": [{"value": "0A:2B:4C:6D:8E:9F"}],
      "field_sequence": [{"value": 3}],
      "field_counter": [{"value": 1}],
      "field_battery_voltage": [{ "value": 1.2 }],
      "field_tilt_sensor": [{"value": "True"}],
      "field_timeout": [{"value":10}]
    }
  }'