API v3.0 (Experimental)¶

Warning

This api is in development. Changes can and will be made without notice.

Warning

Not all sensors/project may provide all measurands that are documented here. That depends on hardware capabilities and project configuration.

The base url is: https://josene.intemo.com/

API methods¶

List devices¶

GET /sensors/v3.0/devices¶

Get a list of devices that are available

Example request:

GET /sensors/v3.0/devices HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "devices": [
        14561,
        14564,
        15300
    ]
}

Example request:

GET /sensors/v3.0/devices?user_field__contains=Amsterdam&type=main HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "devices": [
        14561
    ]
}

Status Codes:

200 OK – OK
403 Forbidden – Authorization error

Query Parameters:

user_field – Show only sensors that have this user_field (case insensitive)
user_field__contains – Show only sensors which user_field contain this value (case insensitive)
hardware_id – Show only sensors that have this hardware_id (case insensitive)
type – [main, sub, all] Show only sensors which are a main or sub board. defaults to all

Get metadata¶

GET /sensors/v3.0/devices/(uint32: sensor_id)¶

Get meta data list for a specific sensor sensor_id

Example request:

GET /sensors/v3.0/devices/14561 HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": 14561,
    "hardware": {
        "id": "0004A30B00012AD0",
        "sensors" : [{"measurand": "NH3 Concentration",
                     "type": "Gas, Calyx, N100 Ammonia , NH3"
                     }],
    },
    "subs": [14562, 14563],
    "main": 14660,
    "location": {
        "latitude": 51.4793,
        "longitude": 5.6570,
        "time": "2023-02-08T08:22:53.972Z",
        "dop": 2.7,
        "type": "gps"
    },
    "outputs": [
        {
            "name": "battery_current.mA"
        },
        {
            "name": "battery_gauge.mCoulomb"
        },
        { " snipped..."},
    ],
    "user_field": "My fancy name",
    "serial_number": "22090019"
}

Query Parameters:

pretty – bool: if true, json will we returned pretty formatted
fields – comma separated list of fields you want to receive, if left out, _all_ data is retrieved. Can be a combination of hardware, hardware.sensors, subs, main outputs, user_field, serial_nuber. Request as few fields as possible for performance reasons. (“outputs” is expensive)

Parameters:

sensor_id – id of device

Status Codes:

200 OK – OK
404 Not Found – sensor_id not found
403 Forbidden – Authorization error

Response JSON Object:

id – sensor_id of the sensor
hardware (object) – Hardware details of the sensor
hardware_id – Hardware id (hex format)
hardware_sensors – List of sensor info (Informative only, format may change)
main – sensor_id of the corresponding main sensor (if any)
subs – sensor_ids of the corresponding sub sensors (if any)
location – Last known location. “gps” location is read from gps in sensor, “fixed” location is fixed. (only available on the main sensor)
user_field – Custom field writable by api user. Useful for naming, cross-referencing or grouping (string, max length = 50)
serial_number – Intemo serial number

Multiple sensor devices can be placed in the same physical sensor. In that case you have one main sensor, and one or more sub-sensors. Every sensor is visible in the api with its own sensor_id and the topology can be derived from the main and subs fields in the response.

Get metadata multiple¶

GET /sensors/v3.0/devices/meta/(comma_separated: sensor_ids)¶

Get meta data list for set of sensors This api is similar to Get metadata but queries multiple sensors in a single request.

For details on response data see Get metadata

Example request:

GET /sensors/v3.0/devices/meta/14561,14562 HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "id": 14561,
        "hardware": {
        },
        "subs": [14562, 14563],
        { " snipped..."},
    },
    {
        "id": 14562,
        { " snipped..."},
    }
]

Query Parameters:

pretty – bool: if true, json will we returned pretty formatted
fields – comma separated list of fields you want to receive, if left out, _all_ data is retrieved. Can be a combination of hardware, hardware.sensors, subs, main outputs, user_field, serial_nuber. Request as few fields as possible for performance reasons. (Especially “outputs” is expensive)

Parameters:

sensor_ids – comma separated list of sensor ids

Status Codes:

200 OK – OK
404 Not Found – None of sensor_ids is found
403 Forbidden – Authorization error

Update metadata¶

POST /sensors/v3.0/devices/(uint32: sensor_id)¶

Update meta data fields list for a specific sensor sensor_id

..note:: In case session based login is used the csrf_token must be passed from the login request

Example request:
POST /sensors/v3.0/devices/14561 HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X
X-CSRFToken: yl5ZTN2NVCyXu8

{
    "user_field": "My fancy name"
}
Example response:
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8
param sensor_id:

id of device

status 201:

OK

status 404:

sensor_id not found

status 400:

Invalid parameter or invalid value

status 403:

Authorization error

jsonparam string user_field:

Update user_field

jsonparam string serial_number:

Update serial_number

jsonparam int hardware_type:

Hardware type (EG: 22000)

jsonparam string hardware_revision:

Hardware rev (Eg: “A03”)

jsonparam string firmware_version:

Firmware version (Eg: “1.0.4”)

Pass an empty value (“”) to erase a field.

Note

You can only update the fields documented here. the other fields are not writable via the API.

Note

Not all api keys have write access enabled. If you POST metadata with an apikey that has write access not enabled you get a 403 with an informative body eg: “token has no write access”

Note

serial_number, hardware_type, hardware_revision, firmware_version are Intemo internal apis. These require special permission. If you try to update these fields with an ApiKey without those permissions you get a 403.

Create Sensor¶

POST /sensors/v3.0/devices¶

Create a new sensor in the database.

..note:: In case session based login is used the csrf_token must be passed from the login request

Example request:
POST /sensors/v3.0/devices/ HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X
X-CSRFToken: yl5ZTN2NVCyXu8

{
    "hardware": {"id": "0004A30B00012AD0"},
    "user_field": "My fancy name"
    "project_id": 2,
    "serial_number": "22090019",
}
Example response:
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "id": 14561
}
param sensor_id:

id of device

status 201:

OK

status 400:

Invalid parameter or invalid value

status 403:

Authorization error

status 409:

Object already existed (hardware id is already known)

jsonparam string hardware.id:

unique hardware identifier

jsonparam string user_field:

user_field

jsonparam string serial_number:

serial_number

jsonparam int hardware_type:

Hardware type (EG: 22000)

jsonparam string hardware_revision:

Hardware rev (Eg: “A03”)

jsonparam string firmware_version:

Firmware version (Eg: “1.0.4”)

jsonparam string project_id:

Project id (sensor gets initially assigned to this project)

>json string id:

Resulting sensor_id of created object

Note

This is an Intemo internal API. Not all api keys have access to this method. If your api key does not have the correct permissions, you get a 403 with an informative body.

Get data¶

GET /sensors/v3.0/devices/(uint32: sensor_id)/timeseries¶

Get sensor data in a time window. This api does support aggregation

Example request:

GET /sensors/v3.0/devices/14561/timeseries?start=2022-12-08T10:00:00Z&end=2022-12-10T12:00:00Z&aggr_method=avg&aggr_window=30m&measurands=all HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": 14561,
    "limited": false,
    "timeseries": [
        {
            "accelero_z.g": 1.07421875,
            "max_audio_125Hz.dbA": 30,
            "max_audio_630Hz.dbA": 26,
            "mom_audio_2_5kHz.dbA": 25,
            "max_audio_total.dbA": 48,
            "time": "2022-12-08T08:22:53.972Z"
        },
        { " snipped ..." },
        { " snipped ..." }

    ]
}

GET /sensors/v3.0/devices/14561/timeseries?start=2022-12-08T10:00:00Z&end=2022-12-10T12:00:00Z&aggr_method=avg&aggr_window=30m&measurands=co2.ppb HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": 14561,
    "timeseries": [
        {
            "co2.ppb":655000,
            "time": "2022-12-08T08:22:53.972Z"
        },
        {
            "co2.ppb":656000,
            "time": "2022-12-08T08:27:53.002Z"
        },
        { " snipped ..." }

    ]
}

Parameters:

sensor_id – id of device

Query Parameters:

measurands – comma separated list of measurands you want to see. Pass ‘all’ to return all. If left out all measurands are shown.
start – ISO 8601 formatted timestamp (UTC), boundary is inclusive
end – ISO 8601 formatted timestamp (UTC), boundary is exclusive
aggr_method – (optional) Aggregation method: Must be one of min, max or avg. If ‘none’ or left out no aggregation is applied, (but max range of start-end is 24 hours in that case)
aggr_window – (mandatory if aggr_method is used). Aggregation window, Can be expressed in seconds, minutes, hours, days: eg 20s, 5m, 1h, 7d Importing, picking a too small aggr_window may result in generating many points, resulting in bad performance)

Status Codes:

200 OK – OK
400 Bad Request – Invalid/missing query parameters (see response for more details)
404 Not Found – sensor_id not found
403 Forbidden – Authorization error

In timeseries a number of measurands is returned.

In timeseries you find a list of measurements. Each measurements contains a set of measurands on a single time. The unit of the measurand is encoded in the measurand name. See Data format for details on the unit abbreviations

Get last data¶

GET /sensors/v3.0/devices/(uint32: sensor_id)/last¶

Get the last sensor data of sensor sensor_id

Example request:

GET /sensors/v3.0/devices/14561/last HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": 14561,
    "accelero_z.g": 1.07421875,
    "max_audio_125Hz.dbA": 30,
    "max_audio_630Hz.dbA": 26,
    "mom_audio_2_5kHz.dbA": 25,
    "max_audio_total.dbA": 48,
    " snipped ...",
    " snipped ..."
    "time": "2018-01-11T08:40:51.521Z"
}

Parameters:

sensor_id – id of device

Query Parameters:

measurands – (Optional) comma separated list of measurands you want to see. (leaving out defaults to show all)

Status Codes:

200 OK – OK
404 Not Found – sensor_id not found
403 Forbidden – Authorization error

The reply contains a number of measurands. See Data format for details how to interpret that unit.

Get last data (multiple)¶

GET /sensors/v3.0/devices/last/(comma_separated: sensor_ids)¶

Get the last sensor data of a series of sensors. This api is similar to Get last data but queries multiple sensors in a single request. This api should be used when querying every sensor individually takes much overhead/latency.

Example request:

GET /sensors/v3.0/devices/last/14561,14562 HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "id": 14561,
        "max_audio_100Hz.dbA": 30,
        " snipped ...",
        " snipped ..."
        "time": "2018-01-11T08:40:51.521Z"
    },
    {
        "id": 14562,
        "max_audio_100Hz.dbA": 32,
        " snipped ...",
        " snipped ..."
        "time": "2018-01-11T08:41:50.123Z"
    }
]

Parameters:

sensor_ids – comma separated list of sensor ids

Query Parameters:

measurands – (Optional) comma separated list of measurands you want to see. (leaving out defaults to show all)

Status Codes:

200 OK – OK. If not all sensors in sensor_ids could be found, we return a 200 with the sensors that do exist.
404 Not Found – None of the sensors in sensor_ids could be found.
403 Forbidden – Authorization error

The reply contains a number of measurands. See Get metadata what the unit is, and see Data format for details how to interpret that unit.

Data format¶

This chapter describes how to interpret the units of the measurands.

Warning

This chapter is not complete.

Some of the units are self explanatory: eg “milliKelvin”, “milliAmpere”, “milliCoulomb”. The ones that are not self explanatory are described in in the table below.

measurand unit conversion¶
unit	description	conversion	example
`degrees`	degrees latitude	longitude
`mdegrees`	milli degrees (angle)
`mV`	milli Volt
`mA`	milli Ampere
`nV`	nano Volt
`mCoulomb`	milli Coulomb
`mK`	milli Kelvin
`dbA`	dB(A) sound pressure
`ppb`	parts per billion		498000 is 498 ppm
`s`	seconds
`lx`	lux
`Pa`	Pascal
`g`	g-force 9.81 m/s^2
`m`	meter
`ugm3`	micro gram per cubic meter
`ngm3`	nano gram per cubic meter
`html`	# html color code eg: 0x808000 = #808000 = olive
`Ohm`	Ohm
`ms`	m/s meter per second (speed)
`mms`	mm/s milli-meter per second (speed)
`uls`	micro liter per second
`milli`	milli
`percent`	relative humidity in %
`K`	Kelvin
`binary`	<undocumented>	for internal use only

wind direction¶

Wind direction is reported by the direction from which is originates where 0 degrees is north, 180 is south.

wind direction¶
degrees	origin	meaning
0	north	wind blowing from north to south
90	east	wind blowing from east to west
180	south	wind blowing from south to north
270	west	wind blowing from west to east.

wind direction¶

Wind direction is reported by the direction from which is originates where 0 degrees is north, 180 is south.

wind direction¶
degrees	origin	meaning
0	north	wind blowing from north to south
90	east	wind blowing from east to west
180	south	wind blowing from south to north
270	west	wind blowing from west to east.

audio format¶

Audio measurements return four types measurements:

average in sample interval
minimum values in sample interval
maximum values in sample interval
momentary level (single measurement)

A sample interval is typically 10s.

Audio levels are send in dB(A), where 0 dB(A) is the lowest, and 127 dB(A) is the highest possible value.

The four types of measurements are distinguished by the prefix in the measurands in the api.

audio types¶
type	prefix	example
average data	avg_audio_	avg_audio_25Hz.dbA
minumum data	min_audio_	min_audio_31_5Hz.dbA
maximum data	max_audio_	max_audio_31_5Hz.dbA
momentary data	mom_audio_	mom_audio_125Hz.dbA

The following table lists all the frequency sub-bands the sensors measure. Each of the audio types above, have the bands below.

audio bands¶
measurand	Freq
`avg_audio_25Hz`	25 Hz
`avg_audio_31_5Hz`	31.5 Hz
`avg_audio_40Hz`	40 Hz
`avg_audio_50Hz`	50 Hz
`avg_audio_63Hz`	63 Hz
`avg_audio_80Hz`	80 Hz
`avg_audio_100Hz`	100 Hz
`avg_audio_125Hz`	125 Hz
`avg_audio_160Hz`	160 Hz
`avg_audio_200Hz`	200 Hz
`avg_audio_250Hz`	250 Hz
`avg_audio_315Hz`	315 Hz
`avg_audio_400Hz`	400 Hz
`avg_audio_500Hz`	500 Hz
`avg_audio_630Hz`	630 Hz
`avg_audio_800Hz`	800 Hz
`avg_audio_1kHz`	1 kHz
`avg_audio_1_25kHz`	1.25 kHz
`avg_audio_1_6kHz`	1.6 kHz
`avg_audio_2kHz`	2 kHz
`avg_audio_2_5kHz`	2.5 kHz
`avg_audio_3_15kHz`	3.15 kHz
`avg_audio_3_15kHz`	4 kHz
`avg_audio_5kHz`	5 kHz
`avg_audio_6_3kHz`	6.3 kHz
`avg_audio_8kHz`	8 kHz
`avg_audio_10kHz`	10 kHz
`avg_audio_12_5kHz`	12.5 kHz
`avg_audio_16kHz`	16 kHz
`avg_audio_20kHz`	20 kHz
`avg_audio_total`	sum of bands

Total audio¶

The sensors measure the audio in 1/3 octave bands. Besides these sub-bands measurands the api exports the ‘total’ audio pressure. This total value is not directly measued but calculated by adding the sub-band data.

total audio types¶
type	measurand
average data	total_avg_audio.dbA
minumum data	total_min_audio.dbA
maximum data	total_max_audio.dbA
momentary data	total_mom_audio.dbA

NB: The total audio values are not plain additions, but rather additions taking into account the logarithmic scales of the dB(A) values. The following code example shows how the total audio fields are calculated.

import numpy as np

def db_sum(levels):
    """Add audio levels

    This is what smartemission does too: https://github.com/smartemission/

    further references:
       http://www.sengpielaudio.com/calculator-spl.htm

    :param levels: list of levels (dB).
    :type levels: list
    :return: sum of audio levels
    :rtype: float

    >>> '%.1f' % db_sum([80])
    '80.0'
    >>> '%.2f' % db_sum([80, 80, 80])
    '84.77'
    >>> '%.2f' % db_sum([80] * 30)
    '94.77'
    >>> '%.2f' % db_sum([0] * 30)
    '0.00'
    """
    levels = np.asanyarray(levels)
    total =  10.0 * np.log10((10.0 ** (levels / 10.0)).sum())

    # Adding 30 zeroes, end up with a dB(A) of 15
    # if that is the case just round down to zero again, that is much clearer
    if total <= 15:
        total = 0

    return total

Login API methods¶

Login¶

POST /sensors/v3.0/login¶

Login an api client using session based authentication.

Example request:

POST /sensors/v3.0/login HTTP/1.1
Host: josene.intemo.com
Content-Type: application/json

{
    "username": "api-user",
    "password": "secret"
}

Example response:

HTTP/1.1 201 CREATED
Set-Cookie: sessionid=Qjjel7y61vzol5elhwu3je6enq1goe44 expires=Wed, 09 Mar 2022 16:01:31 GMT; HttpOnly; Max-Age=1209600; Path=/;  Secure
Content-Type: application/json

{
    "message":"authenticated",
    "csrf_token":"yl5ZTN2NVCyXu8"
}

Status Codes:

201 Created – OK. Logged in. When passing sessionid as Cookie, api requests are allowed.
401 Unauthorized – Authorization error. credentials are not accepted

Logout¶

POST /sensors/v3.0/logout¶

Force a logout, invalidates your session cookie.

If a session is not explicitly logged out, the session cookie stays valid until it expires.

..note:: Requires the csrf_token from the login api in the X-CSRFToken http header.

Example request:

POST /sensors/v3.0/logout HTTP/1.1
Host: josene.intemo.com
X-CSRFToken: yl5ZTN2NVCyXu8
Cookie: sessionid=Qjjel7y61vzol5elhwu3je6enq1goe44

Example response:

HTTP/1.1 201 CREATED

Status Codes:

201 Created – OK. Logged out.

API v3.0 (Experimental)¶

API methods¶

List devices¶

Get metadata¶

Get metadata multiple¶

Update metadata¶

Create Sensor¶

Get data¶

Get last data¶

Get last data (multiple)¶

Data format¶

wind direction¶

wind direction¶

audio format¶

Total audio¶

Navigation

Related Topics