In order to ingest data into ZENSIE, a sensor type has to be created. A sensor type contains information such as the metrics and units (e.g. Temperature = ºC), data types and expected values. In order to create a new sensor type this endpoint can be used: POST /sensor-type/organization/{organizationId}

If we want to ingest data for counting insects and temperature we can do a POST request to

POST https://api.30mhz.com/sensor-type/organization/{organizationId}

The body would look like this:

{
    "name": "Insect count and temperature",
    "description": "Counting insects in a greenhouse",
    "icon": "<i class=\"material-icons\">favorite</i>",
    "color": "#71cee9",
    "decimals": 1
    "metrics": ["count","temperature"],
    "jsonKeys": ["bug", "temp"],
    "jsonLabels": ["Bug", "Temperature"],
    "dataTypes": ["long", "double"],
    "external": true
}

name
The name of the sensor type

description
A description of the sensor type

icon
The icon of the sensor (will appear in the sensor list + widgets). To view possible icons, visit https://material.io/tools/icons/

color
Color used for widgets

decimals
The precision of the measurements. If we have 1 decimal, we will ingest values like 10.4 or 8.1.

metrics
Id’s of metrics. Metrics determine what users see in the dashboard when viewing graphs. Temperature metric for example, displays the unit ºC or F. To get a list of possible metrics, this endpoint can be used:  GET /metric

jsonKeys
Json keys etermine how data will be stored and retrieved.

jsonLabels
Json labels determine what the user sees when selecting the metrics. If we for example have 2 temperature metrics with json keys temp1 and temp2, we can use the json labels to distinguish. E.g. Temperature greenhouse A, Temperature outside.

dataTypes
Data types determine the type of data that will be stored per json key. The possible data types are

["long", "double", "boolean", "string"]

external
Because we are adding external data, this property has to be set to true.

organizationId in the post url
The organization the sensor type will be added to.

Creating import checks

After the sensor type is created we can use this sensor type create import checks. These checks can be used to ingest data. Read more here

30MHz provides a REST API to access the data collected by ZENSIE via web checks and sensors.

To use it, you will need to create an API key. You can do this by going to the sidebar, click on Account Settings, and select the tab Developer.

Click on the “Request new API key” button.

A dialog will appear showing the API key, which you can copy and use to connect to the API.

API Documentation

The API documentation can be found at https://api.30mhz.com/api/swagger. There are two(2) ways to try the API; using postman, or through the command line.

Example using postman

In this example, we will show you how to use postman to get all the checks of your organization.

Go to swagger documentation and find the description of the endpoint that returns all checks of a given organization https://api.30mhz.com/api/swagger#!/check/getOrganizationChecks.

Note the URL you need to make the call, and the required fields. In this example the required field is the organization id.

To find your organization id, go to ZENSIE dashboard, Account Settings, at the Organization tab

Alternatively, you can find your organization id from the url at the ZENSIE page: 

Download a free version of postman here. Open the application and fill in the required fields:

GET https://api.30mhz.com/api/check/organization/{{organization id}}

Headers
Authorization: {{your API key}}
Content-Type: application/json

The reply is a JSON object and it should look like this:

Example using the command line

Here we will show you how to get all checks from your organization using the command line:

1. Open a command line interface (eg. Terminal for Mac, Command Prompt for Windows).
2. The CURL command that you need for getting all checks of the organization is:

curl -XGET -H 'Content-Type: application/json' -H 'Authorization: your API key' https://api.30mhz.com/api/check/organization/example_id

If you want to save the output of the command in a file you can add at the end of the command >>output.txt like this:

curl -XGET -H 'Content-Type: application/json' -H 'Authorization: your API key' https://api.30mhz.com/api/check/organization/example_id >>output.txt

The data stored in the output.txt file are in a json format. If you are not familiar with it and you want to see the data in a table format, you can use an online JSON to CSV converter (for example here).

Just copy the data from the output.txt file and paste them into the indicated field at the converter page. The result should look like this:

A very common use case when using our API is to get the values of specific sensors. Often we need the current value of a sensor. Other times we need the historical values over a period of time.

To retrieve data for a given sensor, we first need to find the id of this sensor. One way to do this is to go to the sensor in the ZENSIE dashboard (Sensors > click on the sensor you are interested in) and look at its URL in the browser:

Sensor URL example

Another option would be to get all the sensors from an organization using an API call (see this page for an example).

For doing any API call, it’s necessary to generate and use an API key. This can be generated once and used always after that (Go to Account Settings > Developer).

Here are a couple of examples to request data from a temperature/humidity sensor with the unique id “39555cf5-3081-400c-96cf-ff8d9cdea173”. We are using the following API endpoint:

We need to make a GET request, passing the sensor id, and date/time interval. For example, in this case we request the average values per day from the 1st to the 4rd of November of 2017:

curl -XGET \
    -H "Content-type: application/json" \
    -H 'Authorization: <API key>' \
    "https://api.30mhz.com/api/stats/check/39555cf5-3081-400c-96cf-ff8d9cdea173/from/2017-11-01T00:00:00Z/until/2017-11-04T00:00:00Z?statisticType=averages&intervalSize=1d"

This could return for example:

dsf

{ 
  "1509494400000": 
    { "sht25.temp": 18.601995752298404, 
      "sht25.humidity": 59.27995778537517 
    }, 

    "1509580800000": 
      { "sht25.temp": 18.30961109134886, 
      "sht25.humidity": 58.49782640139262 
      }, 

    "1509667200000": 
      { "sht25.temp": 17.93818057510588, 
        "sht25.humidity": 58.11836816999647 
      }
}

This shows the average temperature and humidity for each day, the key in each case being the timestamp.

We could also request the minimum or maximum values for a period by using statisticType=mins or statisticTypes=maxs respectively.

We could change the intervalSize and request it per hour, with intervalSize=1h, or per minute (1m), 5 minutes (5m), 5 days (5d), monthly (M), etc.

Similarly, if we would want the current value for a sensor, we could use the following API endpoint:

And we could call it for the sensor of the example in this way:

curl -XGET \
    -H "Content-type: application/json" \
    -H 'Authorization: <API key>' "https://api.30mhz.com/api/stats/check/56aac51f-5966-47da-8824-eaf36c8e4737"

We would get something similar to this:

{ "checkId": "56aac51f-5966-47da-8824-eaf36c8e4737", 
  "timestamp": "2017-11-21T13:10:45Z", 
  "lastRecordedStats": 
      { "sht25.temp": "16.79", 
        "sht25.humidity": "62.93" 
      }, 
  "json": null, 
  "code": null, 
  "message": null, 
  "matchCondition": null
}

where the current values are returned in lastRecordedStats property.

All the API endpoints to get data for a sensor or a set of sensors can be found in the Swagger documentation.

Creating import checks
The first step is creating import checks. An import check contains all the data of a sensor and creates an endpoint to which values can be sent. Import checks can be created by navigating to the checks view. At the bottom right, the plus button can be clicked to add a new sensor. We then can click on the external sensor option

We fill in the name, select the sensor type and click create.

Sensor types
Sensor types contain the definition of how data is formatted and should be displayed. A sensor type contains information such as the metric + unit (e.g. Temperature = ºC), data types and expected json values. Read here on how to create your own sensor type

Sending data to an import check
The last step is sending data to the api. After saving the check, we see the settings page. Here the endpoint is shown with an example call.

We can do a post to

https://api.30mhz.com/api/ingest/organization/30mhz.com

With these values (values change based on import check and sensor type):

[ 
  { 
  "checkId": "import_check_id", 
  "timestamp": "A valid ISO 8601 DateTime format value with an explicitly set timezone value (e.g. 2017-01-17T19:23:02Z, 2017-01-17T19:23:02+06:45).", 
  "data": 
    {
      "temp": "double", 
      "hum": "double" 
    }, 
  "status": "ok || fail", 
  "error": "custom error text message" 
  } 
]

Notice that we are sending the values inside an array. We can send multiple sensor values (multiple import checks) in one call:

[{import_check_1...},{import_check_2...},{etc...}]

API Keys
Make sure you add your api keys to the Authorization header: find out how to generate and use api keys.