===================== API v1.2 (deprecated) ===================== .. based on https://github.com/Geonovum/smartemission/blob/master/docs/specs/rawsensor-api/rawsensor-api.txt .. warning:: This v1.2 api is deprecated, see :doc:`api` 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 ------------ .. http:get:: /sensors/v1.2/devices Get a list of devices that are available **Example request**: .. sourcecode:: http GET /sensors/v1.2/devices HTTP/1.1 Host: josene.intemo.com Authorization: Bearer yEUqAXfH06WPr81IKU1X **Example response**: .. sourcecode:: http 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 200: OK :status 403: Authorization error .. _v12_meta: Get metadata ------------ .. http:get:: /sensors/v1.2/devices/(uint32:sensor_id) Get meta data list for a specific sensor `sensor_id` **Example request**: .. sourcecode:: http GET /sensors/v1.2/devices/14561 HTTP/1.1 Host: josene.intemo.com Authorization: Bearer yEUqAXfH06WPr81IKU1X **Example response**: .. sourcecode:: http 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" } :param sensor_id: id of device :status 200: OK :status 404: `sensor_id` not found :status 403: Authorization error :resjson id: `sensor_id` of the sensor :resjson hardware_id: hardware_id of the sensor :resjson main: `sensor_id` of the corresponding main sensor (if any) :resjson subs: sensor_ids of the corresponding sub sensors (if any) .. TODO:: more documentation 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 ---- .. http:get:: /sensors/v1.2/devices/(uint32:sensor_id)/timeseries Get the available days of timeseries for a specific sensor `sensor_id`. **Example request**: .. sourcecode:: http GET /sensors/v1.2/devices/14561/timeseries HTTP/1.1 Host: josene.intemo.com Authorization: Bearer yEUqAXfH06WPr81IKU1X **Example response**: .. sourcecode:: http 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" } :param sensor_id: id of device :status 200: OK :status 404: `sensor_id` not found :status 403: Authorization error Hours ----- .. http: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**: .. sourcecode:: http GET /sensors/v1.2/devices/14561/timeseries/20171208 HTTP/1.1 Host: josene.intemo.com Authorization: Bearer yEUqAXfH06WPr81IKU1X **Example response**: .. sourcecode:: http 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" } :param sensor_id: id of device :param date: YYYYMMDD encoded date :status 200: OK :status 404: `sensor_id` not found :status 403: 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 -------- .. http: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**: .. sourcecode:: http GET /sensors/v1.2/devices/14561/timeseries/20171208/9 HTTP/1.1 Host: josene.intemo.com Authorization: Bearer yEUqAXfH06WPr81IKU1X **Example response**: .. sourcecode:: http 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 ..." } ] } :param sensor_id: id of device :param date: YYYYMMDD encoded date :param hour: hour :status 200: OK :status 404: `sensor_id` not found :status 403: Authorization error In `timeseries` you find a list of measurements. Each measurements contains a set of measurands on a single `time`. See :ref:`v12_meta` what the unit is, and see :ref:`v12_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 .. _v12_last_data: Get last data ------------- .. http:get:: /sensors/v1.2/devices/(uint32:sensor_id)/last Get the last sensor data of sensor `sensor_id` **Example request**: .. sourcecode:: http GET /sensors/v1.2/devices/14561/last HTTP/1.1 Host: josene.intemo.com Authorization: Bearer yEUqAXfH06WPr81IKU1X **Example response**: .. sourcecode:: http 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" } :param sensor_id: id of device :status 200: OK :status 404: `sensor_id` not found :status 403: Authorization error The reply contains a number of measurands. See :ref:`v12_meta` what the unit is, and see :ref:`v12_data-format` for details how to interpret that unit. Get last data (multiple) ------------------------ .. http: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 :ref:`v12_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**: .. sourcecode:: http GET /sensors/v1.2/devices/last/14561,14562 HTTP/1.1 Host: josene.intemo.com Authorization: Bearer yEUqAXfH06WPr81IKU1X **Example response**: .. sourcecode:: http 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" } ] :param sensor_ids: comma separated list of sensor ids :status 200: OK. If not all sensors in `sensor_ids` could be found, we return a 200 with the sensors that do exist. :status 404: None of the sensors in `sensor_ids` could be found. :status 403: Authorization error The reply contains a number of measurands. See :ref:`v12_meta` what the unit is, and see :ref:`v12_data-format` for details how to interpret that unit. .. _v12_data-format: 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. .. csv-table:: measurand unit conversion :header: 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 :ref:`v12_audio-format` ``RGB8``, Color coding, html style color coding range 0-255, Red:FF0000 Green:00FF00 Blue:0000FF see :ref:`v12_examples` ``mDegrees``, milli degrees (angle),, 360000 is 360 degrees ``mm/s``, milli meters per second,, 1000 is 1 m/s ``binary``, , 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. .. csv-table:: wind direction :header: 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. .. _v12_audio-format: audio format ------------ Audio measurements return four types measurements: 1. average in sample interval 2. minimum values in sample interval 3. maximum values in sample interval 4. momentary level (single measurement) .. csv-table:: audio types :header: 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 :ref:`v12_examples` how to convert ``combined dB(A)`` to dB(A) The resulting dB(A) is the sound pressure with and A-weighting. .. csv-table:: audio bands :header: 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)`` .. _v12_examples: examples -------- example routine to convert encoded latitude/longitude to degrees .. code-block:: python 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)`` .. code-block:: python 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] .. code-block:: python 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] .. TODO:: Add chapter that describes the measurands