Skip to content

Getting Started

In order to access the API your organization must be registered in our system and you must have user account credentials.

Logging in

Before you can gain access to the API, you must have a user account. The POST user authentication route is http://api.stevens-connect.com/authenticate. A login request can be made as follows:

curl -F "email=your@email.com" -F "password=thisiswherethepasswordgoes" -X POST "http://api.stevens-connect.com/authenticate")

A successful login request will return the following JSON response object

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

Every request after logging in requires use of a JWT token. The first one 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.

Configuration JSON Object

Once logged in, you can retrieve your company's configuration JSON object referred to as the 'config packet' with the following request:

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

A successful request will return the following response:

{
  "config_packet": {
    "projects": [
      {
        "id": 1,
        "company_id": 1,
        "name": "Project Name",
        "public_key": "your_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
      },
      .....
    ],
    ....
  }
}

Administration JSON Object

To retrieve your company's admin configuration JSON object which contains company info and all user's account info with the following request:

curl -H 'Authorization: bearer eyJ0eXAiOiJ.......' http://api.stevens-connect.com/company/<company_id>

A successful request will return the following response:

{
  data: {
    company: {
    city: "Your city"
    contact: "yourcompanyemail@emaildomain.com"
    country: "Your Country"
    id: 00
    name: "Your Company Name"
    phone: "+15555555555"
    projects: [{…}, {…}, {…}, {…}, {…}, {…}, {…}]
    state: "OR"
    street: "123 Your Company Rd"
    users: [{…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}]
    zip: "12345"
    }
    errors: false
  }
}

Getting Data

You can retrieve a sensor channel's data readings from the API with the following request:

curl -H 'Authorization: bearer eyJ0eXAiOiJKV1Q...' http://api.stevens-connect.com/project/{project_id}/readings/v3/channels?channel_ids={channel_id,channel_id...}&range_type=relative&start_date=null&end_date=null&minutes=1440&transformation=none

Query Parameters

  • channel_ids (required): one or more channel ids to get readings for. If more than one, separate with commas. (ie 1,2,3)
  • range_type (required): either 'relative' or 'absolute'
  • transformation (optional, default none): none, average-daily, accumulate, rate-of-change
  • start_date (required if range_type is absolute): start date of query. (ie 2021-04-17 13:00:00)
  • end_date (required if range_type is absolute): end date of query. (ie 2021-04-18 13:00:00)
  • minutes (required if range_type is relative): number of minutes to query (ie 1440 for 24 hours)
  • user_timezone (conditionally required): Your local time zone, or the time zone you wish all readings to be converted to. Required if the users timezone_pref_id is set to 2, ignored otherwise. See User Time Zone Preference section for more details

A successful request will return a response similar to the example below:

{
  "errors":false,
  "data": {
    "readings": {
      "8043": [
        {
          "channel_id":8043,
          "reading":14.06,
          "timestamp":"2021-04-17 13:00:00"
        },
        {
          "channel_id":8043,
          "reading":13.97,
          "timestamp":"2021-04-17 14:00:00"
        },
        ...
      ]
    },
    "function_readings":[],
    "query_time":1524081658,
    "apply_type":"fresh"
  }
}

User Time Zone Preference

How timestamps are handled and converted when getting data will depend on the users timezone_pref_id. The stations timezone_name needs to be set correct for options 1 and 2 to work correctly. If you don't want to think about time zones, choose option 3 and timestamps will be not adjusted.

timezone_pref_id options:

  • 1 - UTC

Data returned from the /readings routes will have every timestamp converted to UTC time. When searching, start_date and end_date should also be UTC.

  • 2 - Local

Data returned from the /readings routes will have every timestamp converted to the user_timezone query parameter. When searching, start_date and end_date should also be in that same time zone.

  • 3 - Station

Data returned from the /readings routes will be the original time zone it was reported in. This time zone is expected to be the value set on that station, but has no effect on data returned.