Skip to content

NovaStar Reference / Data Formats / Stevens Connect

Overview

The Stevens Connect web services provide access to data from Stevens Connect sensors and data collection units (DCUs), in JSON format.

Stevens Connect website

At the time that this documentation was written, no formal documentation exists for the Stevens API.

Data Structure

Based on interactions with the API, it appears that the data structure looks like the following:

Data / Projects / Stations / Sensors / Channels

Stevens to NovaStar Data Mapping

Normal NovaStar naming conventions should be followed, while clearly indicating Stevens station and sensor identifiers.

  1. Stevens station id should be defined as the NovaStar Station Remote Tag
  2. Stevens channel id should be defined as the NovaStar Point Remote ID
  3. The nspollstevensapi program depends on a mapping between the channel IDs and NovaStar Point Remote ID.
  4. The script will file data for any NovaStar Points that have Point Remote IDs matching the Stevens Connect Channel IDs.

Steps to retrieve data from the Stevens API

1. Make a request to the log in to the authenticate URL with email and password.

Auth Request:

curl -d "email=youremail@email.com&password=thisiswherethepasswordgoes" -X POST http://api.stevens-connect.com/authenticate

2. A JavaScript Web Token is provided on successful login.

All future requests will return a new token in the response X-Token header. Each token will expire 60 seconds after use.

Auth Response:

  {
    "errors":false,
    "data": {
      "token":"eyJ0eXAiOiJ.......blah",
      "user": {
        "id":1,
        "company_id":1,
        "name":"Mike",
        "email":"youremail@email.com",
        "phone":"5555555555",
        "sms":"+1 555 555 5555",
        "alarm_email":1,
        "alarm_sms":1,
        "alarm_voice":0,
        "member_level_id":2,
        "status":1
      }
    }
  }

3. Make a request for the configuration packet.

The packet will contain an object describing all projects, stations, sensors, channels, data dictionaries for units, etc.

Configuration Request:

  curl -H 'Authorization: bearer eyJ0eXAiOiJ.......blah' http://api.stevens-connect.com/config-packet

4. Receive the configuration packet.

This can be parsed to extract useful information to be used in data requests.

Configuration Response:

  { 
    "config_packet": { 
      "projects": [ 
        { 
          "id": 1, 
          "company_id": 1, 
          "name": "Project Name", 
          "public_key": "...", 
          "status": 1, 
          "stations": [ 
            { 
              "id": 1, 
              "project_id": 1, 
              "sui": "....", 
              "name": "Bodie Hills", 
              "sensors": [ 
                { 
                  "id": 1, 
                  "station_id": 1, 
                  "name": "Sensor name", 
                  "status": 1, 
                  "reporting": 3600, 
                  "logging": 3600, 
                  "channels": [ 
                    { 
                      "id": 1, 
                      "sensor_id": 1, 
                      "name": "Air Temperature Minimum (degF)", 
                      "unit_id": 1 
                    }, 
      ] 
          ], 
      "units": [ 
        { 
          "id": 58, 
          "name": "Acre Feet", 
          "unit": "AcFt", 
          "company_id": 0 
        }, 
      ], 
    } 
  }

5. Parse the response to form the data request

Once the configuration packet has been retrieved, the JSON can be parsed (e.g., use the jq program) and gather a list of channel IDs that are of interest. In order to make a data request, the following parameters will need to be specified:

Data Request Parameters:

  1. channel_ids (required): one or more channel ids to get readings for. If more than one, separate with commas (e.g., 1,2,3).
  2. range_type (required): either relative or absolute
  3. start_date (required if range_type is absolute): start date of query (e.g., 2018-04-17 13:00:00)
  4. end_date (required if range_type is absolute): end date of query (e.g., 2018-04-18 13:00:00)
  5. minutes (required if range_type is relative): number of minutes to query (e.g., 1440 for 24 hours)
  6. user_time (required): local time of query (e.g., 2018-04-18 13:00:00)

6. Once a list of Channel IDs has been retrieved, a data request can be made.

Data Request 

curl -H 'Authorization: bearer eyJ0eXAiOiJKV1Q.......blah' http://api.stevens-connect.com/project/45/readings?channel_ids=8043&range_type=relative&start_date=null&end_date=null&minutes=1440&transformation=none&user_time=2018-04-18%2013:00:00

7. Data response

The actual data readings response will contain entries for the channels requested based on the query parameters (see #5).

Data Response 

  {
    "errors":false,
    "data": {
      "readings": {
        "8043": [
          {
            "channel_id": 8043,
            "reading": 14.06,
            "timestamp": "2018-04-17 13:00:00"
          },
          {
            "channel_id":8043,
            "reading":13.97,
            "timestamp":
            "2018-04-17 14:00:00"
          }
          ...
        ]
      }
    }
  }

Standard NovaStar Properties

Limitations

  1. Data are received in the time zone that the transmitter lives in. NovaStar will file it as-is.
  2. The sendrpt provides a time offset parameter that can be utilized to shift data into appropriate time zones, but this will be on case by case basis.

Importing Data into NovaStar

Stevens data can be imported into NovaStar using the nspollstevensapi program.

Exporting Data from NovaStar

Exporting data from NovaStar into Stevens is not implemented.