API v1.2 (deprecated)¶

Warning

This v1.2 api is deprecated, see API v2.0 instead. This v1.2 api will stay online, but any new features are only added to the latest api.

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

API methods¶

List devices¶

GET /sensors/v1.2/devices¶

Get a list of devices that are available

Example request:

GET /sensors/v1.2/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": [
        "/sensors/v1.2/devices/14561",
        "/sensors/v1.2/devices/14564",
        "/sensors/v1.2/devices/15300"
    ]
}

Status Codes:

200 OK – OK
403 Forbidden – Authorization error

Get metadata¶

GET /sensors/v1.2/devices/(uint32: sensor_id)¶

Get meta data list for a specific sensor sensor_id

Example request:

GET /sensors/v1.2/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"},
    "last": "/sensors/v1.2/devices/14561/last",
    "subs": [14562, 14563],
    "main": 14660,
    "outputs": [
        {
            "label": "Battery Current",
            "name": "p_batterycurrent",
            "unit": "milliAmpere"
        },
        {
        "label": "Battery Gauge",
        "name": "p_batterygauge",
        "unit": "milliCoulomb"
        },
        { " snipped..."},

    ],
    "timeseries": "/sensors/v1.2/devices/14561/timeseries"
}

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_id – hardware_id of the sensor
main – sensor_id of the corresponding main sensor (if any)
subs – sensor_ids of the corresponding sub sensors (if any)

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.

Days¶

GET /sensors/v1.2/devices/(uint32: sensor_id)/timeseries¶

Get the available days of timeseries for a specific sensor sensor_id.

Example request:

GET /sensors/v1.2/devices/14561/timeseries HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

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

{
    "days": [
        "/sensors/v1.2/devices/14561/timeseries/20171207",
        "/sensors/v1.2/devices/14561/timeseries/20171208",
        "/sensors/v1.2/devices/14561/timeseries/20171215",
        "/sensors/v1.2/devices/14561/timeseries/20171216",
        "/sensors/v1.2/devices/14561/timeseries/20171217"
    ],
    "id": "14561"
}

Parameters:

sensor_id – id of device

Status Codes:

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

Hours¶

GET /sensors/v1.2/devices/(uint32: sensor_id)/timeseries/(int: date)¶

Get the available days of timeseries for a specific sensor sensor_id.

Example request:

GET /sensors/v1.2/devices/14561/timeseries/20171208 HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

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

{
    "date": "2017/12/08",
    "hours": [
        9,
        10,
        11,
        12,
        13,
        14
    ],
    "id": "14561"
}

Parameters:

sensor_id – id of device
date – YYYYMMDD encoded date

Status Codes:

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

Note

Date/Time is in UTC
The hour number ranges from 1 to 24; 1 means from 0:00:00 until 0:59:59
The date should include zero padding, so 1 january 2018 should be encoded as 2018010

Get data¶

GET /sensors/v1.2/devices/(uint32: sensor_id)/timeseries/(int: date)/(int: hour)¶

Get all sensor data in time window date and hour for sensor sensor_id.

Example request:

GET /sensors/v1.2/devices/14561/timeseries/20171208/9 HTTP/1.1
Host: josene.intemo.com
Authorization: Bearer yEUqAXfH06WPr81IKU1X

Example response:

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

{
    "date": "2017/12/08",
    "hour": 9,
    "id": "14561",
    "timeseries": [
        {
            "t_audio0": 1248512,
            "t_audioplus1": 921880,
            "t_audioplus2": 1119244,
            "t_audioplus3": 1514266,
            "t_audioplus4": 1711131,
            "t_audioplus5": 1973533,
            "t_audioplus6": 2170912,
            "t_audioplus7": 2170913,
            "t_audioplus8": 2302241,
            "t_audioplus9": 2171170,
            "time": "2017-12-08T08:22:53.972Z"
        },
        { " snipped ..." },
        { " snipped ..." }

    ]
}

Parameters:

sensor_id – id of device
date – YYYYMMDD encoded date
hour – hour

Status Codes:

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

In timeseries you find a list of measurements. Each measurements contains a set of measurands on a single time. See Get metadata what the unit is, and see Data format for details how to interpret that unit.

Note

Date/Time is in UTC
The hour number ranges from 1 to 24; 1 means from 0:00:00 until 0:59:59
The date should include zero padding, so 1 januari 2018 should be encoded as 2018010

Get last data¶

GET /sensors/v1.2/devices/(uint32: sensor_id)/last¶

Get the last sensor data of sensor sensor_id

Example request:

GET /sensors/v1.2/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",
    "t_audio0": 1512448,
    "t_audioplus1": 1907479,
    "t_audioplus2": 1842463,
    "t_audioplus3": 2236193,
    "t_audioplus4": 2237218,
    "t_audioplus5": 3289636,
    "t_audioplus6": 2697772,
    "t_audioplus7": 2368294,
    "t_audioplus8": 2368549,
    "t_audioplus9": 2237218,
    " snipped ...",
    " snipped ..."
    "time": "2018-01-11T08:40:51.521Z"
}

Parameters:

sensor_id – id of device

Status Codes:

200 OK – OK
404 Not Found – sensor_id not 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.

Get last data (multiple)¶

GET /sensors/v1.2/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/v1.2/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",
        "t_audio0": 1512448,
        " snipped ...",
        " snipped ..."
        "time": "2018-01-11T08:40:51.521Z"
    },
    {
        "id": "14562",
        "t_audio0": 1712338,
        " snipped ...",
        " snipped ..."
        "time": "2018-01-11T08:41:50.123Z"
    }
]

Parameters:

sensor_ids – comma separated list of sensor ids

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
`ppb`	parts per billion		498000 is 498 ppm
`ng/m3`	nano gram per cubic meter		118000 is 118 ug/m3
`encoded latitude`	encoded latitude of position	uint32_t Bit 31 0 = North, 1 = South Bits 30 to 28 not used Bits 27 to 20 whole degrees Bits 19 to 0 fractional degrees * 1000000	54576090 is 52.050138 degrees N
`encoded longitude`	encoded longitude of position	Bit 31 0 = East, 1 = West rest same as latitude	5914086 is 5.671206 degrees E
`oG`	encoded acceleration	(value -512) / 256	774 is 1.02 G
`m%RH`	relative humidity	milli %RH - value/1000	41211 is 41.211 %RH
`combined dB(A)`	3 audio bands combined	Each byte containds dB(A) of 1/3 octave band	see audio format
`RGB8`	Color coding	html style color coding range 0-255	Red:FF0000 Green:00FF00 Blue:0000FF see examples
`mDegrees`	milli degrees (angle)		360000 is 360 degrees
`mm/s`	milli meters per second		1000 is 1 m/s
`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.

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)

audio types¶
type	prefix	example
average data	v_	v_audio0
minumum data	u_	u_audio0
maximum data	t_	t_audio0
momentary data	s_	s_audio0

For each of these types we measure 30 1/3 Octave subbands. 3 such subbands are combined in a single measurand using the combined dB(A) format. See examples how to convert combined dB(A) to dB(A) The resulting dB(A) is the sound pressure with and A-weighting.

audio bands¶
measurand	sub-band	Freq
`v_audio0`	sub1	25 Hz
`v_audio0`	sub2	31.5 Hz
`v_audio0`	sub3	40 Hz
`v_audioplus1`	sub1	50 Hz
`v_audioplus1`	sub2	63 Hz
`v_audioplus1`	sub3	80 Hz
`v_audioplus2`	sub1	100 Hz
`v_audioplus2`	sub2	125 Hz
`v_audioplus2`	sub3	160 Hz
`v_audioplus3`	sub1	200 Hz
`v_audioplus3`	sub2	250 Hz
`v_audioplus3`	sub3	315 Hz
`v_audioplus4`	sub1	400 Hz
`v_audioplus4`	sub2	500 Hz
`v_audioplus4`	sub3	630 Hz
`v_audioplus5`	sub1	800 Hz
`v_audioplus5`	sub2	1 kHz
`v_audioplus5`	sub3	1.25 kHz
`v_audioplus6`	sub1	1.6 kHz
`v_audioplus6`	sub2	2 kHz
`v_audioplus6`	sub3	2.5 kHz
`v_audioplus7`	sub1	3.15 kHz
`v_audioplus7`	sub2	4 kHz
`v_audioplus7`	sub3	5 kHz
`v_audioplus8`	sub1	6.3 kHz
`v_audioplus8`	sub2	8 kHz
`v_audioplus8`	sub3	10 kHz
`v_audioplus9`	sub1	12.5 kHz
`v_audioplus9`	sub2	16 kHz
`v_audioplus9`	sub3	20 kHz

See example below how to decode combined dB(A)

examples¶

example routine to convert encoded latitude/longitude to degrees

def to_deg(encoded_deg):
    """Covert encoded lat/lon to degrees

    :return: lat/long  eg  5.671056 or 52.050138
    """

    # Bits 31         0 = North, 1 = South
    # Bits 30 to 28   N/U
    # Bits 27 to 20   Whole degrees
    # Bits 19 to  0   Fractional Degrees
    deg = (encoded_deg & 0xFF00000) >> 20
    part_deg = (encoded_deg & 0xFFFFF) / 1000000.0

    deg += part_deg

    if encoded_deg & (1 << 31):
        return -deg
    else:
        return deg

example routine to convert combined dB(A) to dB(A)

def get_bands(value):
    """decode 3 audio bands from a combined josene audio band value

    :return: [sub1, sub2, sub3]  in dB(A) each
    """
    sub1 = value & 0xff
    sub2 = (value >> 8) & 0xff
    sub3 = (value >> 16) & 0xff

    return [sub1, sub2, sub3]

def get_color(value):
    """decode RGB8

    Decode RGB8 and return Red, Green, Blue values (min 0, max 255)

    :return: [Red, Green, Blue]
    """
    red = (value >> 16) & 0xff
    green = (value >> 8) & 0xff
    blue = value & 0xff

    return [red, green, blue]

API v1.2 (deprecated)¶

API methods¶

List devices¶

Get metadata¶

Days¶

Hours¶

Get data¶

Get last data¶

Get last data (multiple)¶

Data format¶

wind direction¶

audio format¶

examples¶

Navigation

Related Topics