Sensor Data Platform

POST /api/providers/create ¶

Creates a new data provider.

Parameters:	name (string) – provider name (required) acronym (string) – provider acronym description (string) – provider description email (string) – email address to provider contact (required) username (string) – provider username (required) password (string) – provider password (required)
Request: JSON Object
Response: JSON Object:
	providerid (int) – provider identifier token (string) – provider token message (string) – HTTP status text http-status-code (int) – HTTP status code atom (string) – atom URL to provider
Status Codes:	400 Bad Request 500 Internal Server Error error-code (int) – application error 410 - name conflict

Example request:

POST /api/providers/create HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Content-Type: application/json
{
    "name": "Data Provider",
    "acronym": "DP",
    "description": "Provider description",
    "username": "my.username",
    "password": "my100th.Secret.password",
    "email": "my.mail.address@any.domain.com"   
}

Example response:

HTTPS/1.1 201 OK
Content-Type: application/json
{
    "providerid": 10,
    "message": "Created",
    "token": "e37c36ea97a34f6381c749482fb4bba5",
    "http-status-code": 201,
    "atom": "https://sensors.nilu.no/api/providers/10"
}

Note: New data providers are by default shipped with one authentication token. More tokens can be created if required. Also see this section.

POST /api/providers/tokens/new ¶

Creates a new token (with indefinite expiration date) for data provider.

Response: JSON Object:
	providerid (int) – provider identifier token (string) – provider token message (string) – HTTP status text http-status-code (int) – HTTP status code
Status Codes:	400 Bad Request 401 Unauthorized 500 Internal Server Error error-code (int) – application error 500 - not authorized

Example request:

POST /api/providers/tokens/new HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Basic N2Q2YTk2NWMwNWNmNDI2OjMzZTUyMjk1ZmQ=

Example response:

HTTPS/1.1 201 OK
Content-Type: application/json
{
    "providerid": 10,
    "message": "Created",
    "token": "fbedddbdb3874c458413ffa0343e85dc",
    "http-status-code": 201
}

Note: Basic authentication is used. Username and password must therefore be Base64 encoded. Please refer to this section.

POST /api/providers/tokens/new/{string: format} ¶

Creates a new provider token with custom expiration date.

Parameters:	format (string) – Token age format.   Valid formats are:   <n>h = n hours after creation, eg. "5h" <n>d = n days after creation, eg. "5d" <n>M = n months after creation, eg. "5M" <n>Y = n years after creation, eg. "5Y"
Response: JSON Object:
	providerid (int) – provider identifier token (string) – provider token message (string) – HTTP status text http-status-code (int) – HTTP status code
Status Codes:	400 Bad Request 401 Unauthorized 500 Internal Server Error error-code (int) – application error 133 - invalid token age format 500 - not authorized

Example request:

POST /api/providers/tokens/new/10d HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Basic NjFmMGJlMTlkZTFlNDVjOjA4ODM5NzlkMTU=

Example response:

Please refer to this section.

POST /api/providers/tokens/revoke ¶

Revokes the data provider token.

Response: JSON Object:
	providerid (int) – provider identifier message (string) – HTTP status text http-status-code (int) – HTTP status code
Status Codes:	400 Bad Request 401 Unauthorized 500 Internal Server Error error-code (int) – application error 500 - not authorized

Example request:

POST /api/providers/tokens/revoke HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Content-Type: application/json
Authorization: Basic MTE0OWJjZTg1MzU0NDdiOjYwZjdmZmJmYmI=
{
    "token": "bab5bd84df1b4c3d918e6d01597845a1"
}

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "providerid": 10,
    "message": "OK",
    "http-status-code": 200
}

GET /api/providers/{int: id} ¶

Get data provider identified by id.

Parameters:	id (int) – Identifier of data provider.
Response: JSON object:
	id (int) – data provider identifier name (string) – provider name acronym (string) – provider acronym description (string) – provider description atom (string) – provider atom URL created (string, UTC, ISO-8601) – provider creation date
Status Codes:	400 Bad Request 404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/providers/1 HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "id": 1,
    "name": "Norwegian Institute for Air Research",
    "acronym": "NILU",
    "atom": "https://sensors.nilu.no/api/providers/1",
    "description": "Norwegian Institute for Air Research is an independent, nonprofit institution established in 1969.",
    "created": "2020-04-15T08:14:14.3191140Z"
}

GET /api/providers ¶

Get a list of data providers.

Parameters:	id (int) – Identifier of data provider.
Response: JSON Array of Objects:
	id (int) – data provider identifier name (string) – provider name acronym (string) – provider acronym description (string) – provider description atom (string) – provider atom URL created (string, UTC, ISO-8601) – provider creation date
Status Codes:	500 Internal Server Error error-code (int) – application error

Example request:

GET /api/providers HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[{
    "id": 1,
    "name": "Norwegian Institute for Air Research",
    "acronym": "NILU",
    "atom": "https://sensors.nilu.no/api/providers/1",
    "description": "Norwegian Institute for Air Research is an independent, nonprofit institution established in 1969.",
    "created": "2020-04-15T08:14:14.3191140Z"
},
{
    "id": 2,
    "name": "Data Provider",
    "acronym": "DP",
    "atom": "https://sensors.nilu.no/api/providers/2",
    "description": "Description of data provider.",
    "created": "2024-11-18T17:49:03.1865854Z"
}]

GET /api/sensors/providers/{int: id} ¶

Get a list of sensors using the provider id.

Parameters:	id (int) – Identifier of data provider.
Response: JSON Array of Objects:
	Please refer to this section.
Status Codes:	404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/sensors/providers/1 HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

Please refer to this section.

GET /api/data/id/{int: id}/minutc ¶

Gets the oldest sensor data identified by id.

Under re-implementation (temporary unavailable).

Parameters:	id (int) – Identifier of sensor.
Response: JSON Array of Objects:
	id (int) – sensor identifier component (string) – component name unit (string) – component unit value (double) – raw value value_corr (double) – corrected value (default: null) after applying correction logic level (int) – component data level level_corr (int) – corrected data level (default: null) after applying correction logic epsg (int) – sensor position, SRS code timestamp_from_epoch (long) – begin timestamp (Unix Epoch) timestamp_to_epoch (long) – end timestamp (Unix Epoch) longitude (double) – sensor position, longitude latitude (double) – sensor position, latitude altitude (double) – sensor position, altitude qc_flags (object) - quality control (QC) flags for data (default 0 if never set) flags (int) – Numerical representation of the flags bitflags (string) – Bitwise representation of the flags qcs_flags (object) - specific quality control (QCS) flags for data (default 0 if never set) flags (int) – Numerical representation of the flags bitflags (string) – Bitwise representation of the flags
Status Codes:	400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error

Example request:

GET /api/data/id/122/minutc HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Bearer 29febf42749d4b2586ae2daf939924ee

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
X-disclaimer: NILU makes no warranty of any kind, express or implied, concerning the provided data and information (..)
[{
    "id": 122,
    "component": "Humidity",
    "value": 15.98,
    "unit": "%RH",
    "longitude": -90,
    "latitude": 90,
    "altitude": 1,
    "level": 0,
    "epsg": 4326,
    "timestamp_from_epoch": 1588067073,
    "timestamp_to_epoch": 1588067133,
    "qc_flags": {
        "flags": 1,
        "bitflags": "00000001"
    },
    "qcs_flags": {
        "flags": 6,
        "bitflags": "0000000000000110"
    }	
},
{
    "id": 122,
    "component": "PM2.5",
    "value": 2.45,
    "unit": "µg/m³",
    "longitude": -90,
    "latitude": 90,
    "altitude": 1,
    "level": 0,
    "epsg": 4326,
    "timestamp_from_epoch": 1588067073,
    "timestamp_to_epoch": 1588067133,
    "qc_flags": {
        "flags": 9,
        "bitflags": "00001001"
    },
    "qcs_flags": {
        "flags": 62,
        "bitflags": "0000000000111110"
    }	
}]

GET /api/data/id/{int: id}/maxutc ¶

Gets last sensor data identified by id.

Parameters:	id (int) – Identifier of sensor.
Response: JSON Array of Objects:
	id (int) – sensor identifier component (string) – component name unit (string) – component unit value (double) – raw value value_corr (double) – corrected value (default: null) after applying correction logic level (int) – component data level level_corr (int) – corrected data level (default: null) after applying correction logic epsg (int) – sensor position, SRS code timestamp_from_epoch (long) – begin timestamp (Unix Epoch) timestamp_to_epoch (long) – end timestamp (Unix Epoch) longitude (double) – sensor position, longitude latitude (double) – sensor position, latitude altitude (double) – sensor position, altitude qc_flags (object) - quality control (QC) flags for data (default 0 if never set) flags (int) – Numerical representation of the flags bitflags (string) – Bitwise representation of the flags qcs_flags (object) - specific quality control (QCS) flags for data (default 0 if never set) flags (int) – Numerical representation of the flags bitflags (string) – Bitwise representation of the flags
Status Codes:	400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error

Example request:

GET /api/data/id/122/maxutc HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Bearer 25306cf00bb4458da9a14cd7ff3dd4e9

Example response:

Please refer to this section.

GET /api/data/id/{int: id}/fromutc/{string: fromUtc} ¶

Get sensor data using a UTC timestamp. The end UTC date will be 2 months ahead the start UTC date.

Parameters:	id (int) – Identifier of sensor fromUtc (string) – UTC start timestamp using the ISO-8601 format
Response: JSON Array of Objects:
	id (int) – sensor identifier component (string) – component name unit (string) – component unit value (double) – raw value value_corr (double) – corrected value (default: null) after applying correction logic level (int) – component data level level_corr (int) – corrected data level (default: null) after applying correction logic epsg (int) – sensor position, SRS code timestamp_from_epoch (long) – begin timestamp (Unix Epoch) timestamp_to_epoch (long) – end timestamp (Unix Epoch) longitude (double) – sensor position, longitude latitude (double) – sensor position, latitude altitude (double) – sensor position, altitude qc_flags (object) - quality control (QC) flags for data (default 0 if never set) flags (int) – Numerical representation of the flags bitflags (string) – Bitwise representation of the flags qcs_flags (object) - specific quality control (QCS) flags for data (default 0 if never set) flags (int) – Numerical representation of the flags bitflags (string) – Bitwise representation of the flags
Status Codes:	400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error

Example request:

GET /api/data/id/122/fromutc/2020-01-20T09:20:05.13Z HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Bearer c0a7e7a8fcaa4337b3bc97ac4f4db975

Example response:

Please refer to this section.

GET /api/data/id/{int: id}/fromutc/{string: fromUtc}/toutc/{string: toUtc} ¶

Get sensor data using a UTC timestamp range. Date range cannot exceed 2 months.

Parameters:	id (int) – Identifier of sensor fromUtc (string) – UTC start timestamp using the ISO-8601 format toUtc (string) – UTC end timestamp using the ISO-8601 format
Response: JSON Array of Objects:
	id (int) – sensor identifier component (string) – component name unit (string) – component unit value (double) – raw value value_corr (double) – corrected value (default: null) after applying correction logic level (int) – component data level level_corr (int) – corrected data level (default: null) after applying correction logic epsg (int) – sensor position, SRS code timestamp_from_epoch (long) – begin timestamp (Unix Epoch) timestamp_to_epoch (long) – end timestamp (Unix Epoch) longitude (double) – sensor position, longitude latitude (double) – sensor position, latitude altitude (double) – sensor position, altitude qc_flags (object) - quality control (QC) flags for data (default 0 if never set) flags (int) – Numerical representation of the flags bitflags (string) – Bitwise representation of the flags qcs_flags (object) - specific quality control (QCS) flags for data (default 0 if never set) flags (int) – Numerical representation of the flags bitflags (string) – Bitwise representation of the flags
Status Codes:	400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error

Example request:

GET /api/data/id/122/fromutc/2020-01-20T09:20:05.13Z/toutc/2021-01-20T09:20:05.13Z HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Bearer b29adcb8e686415a9d34495dd94fa081

Example response:

Please refer to this section.

GET /api/data/id/{int: id}/{string: period}/stats(?exclude=position|none) ¶

Get last periodic statistics for sensor identified by id.

Outliers are ignored in the calculation.

When ?exclude=position is used in HTTP GET, the aggregation is not performed on distinct sensor positions. Instead the averaged sensor positions are used within the aggregation groups. The aggregation is much slower when not using this filter, especially for moving sensors with a lot of distinct positions.

Parameters:	id (int) – Identifier of sensor period (string) – The period to retrieve statistics for. Accepted value is 'hourly', 'daily', 'weekly' or 'monthly'. exclude (string, optional) - Exclude filter to use during aggregation. Default is none.
Response: JSON Array of Objects:
	id (int) – sensor identifier timestamp_from_epoch (long) – begin timestamp (Unix Epoch) timestamp_to_epoch (long) – end timestamp (Unix Epoch) component (string) – component name level (int) – component data level unit (string) – component unit qc (bool) - quality control flag with two states; 0 or 1. 0: no quality control (component not configured for QC) has been performed on value. 1: quality control has been performed with no outlier flags set. n (int) – sample size of (double) – outlier fraction (OF) of total sample size. Value in interval [0, 1] or -1 when component is not configured for QC. res (int) – original sensor resolution (in seconds) avg (double) – arithmetic average value median (double) – median value (50% percentile) min (double) – minimum value max (double) – maximum value std_dev (double) – standard sample deviation for value var (double) – the variance for value sem (double) – the standard error mean (SEM) for value mse (double) – the mean squared error (MSE) for value cv (double) – the coefficient of variation (CV) for value q1 (double) – first quartile (Q1) ~ 25% percentile q3 (double) – third quartile (Q3) ~ 75% percentile iqr (double) – interquartile range (IQR = Q3 - Q1) epsg (int) – sensor position, SRS code longitude (double) – sensor position, longitude latitude (double) – sensor position, latitude altitude (double) – sensor position, altitude
Status Codes:	400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error

Example request:

GET /api/data/id/117/hourly/stats HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Bearer 3ebf00b6768d48d7a9d597b0f52ffbb2

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[{
    "id": 117,
    "timestamp_from_epoch": 1605164400,
    "timestamp_to_epoch": 1605168000,
    "component": "Humidity",
    "level": 1,
    "unit": "%RH",
    "qc": 0,
    "n": 35,
    "of": -1,
    "res": 60,
    "avg": 67.27,
    "median": 67.36,
    "min": 65.84,
    "max": 68.44,
    "std_dev": 0.71,
    "var": 0.509,
    "sem": 0.121,
    "mse": 0.014542857142857144,
    "cv": 0.010554481938456964,
    "q1": 66.8,
    "q3": 67.88,
    "iqr": 1.0799999999999983,
    "epsg": 4326,
    "longitude": 5.312691,
    "latitude": 60.395897,
    "altitude": 3
},
{
    "id": 117,
    "timestamp_from_epoch": 1605164400,
    "timestamp_to_epoch": 1605168000,
    "component": "PM10.0",
    "level": 1,
    "unit": "µg/m³",
    "qc": 1,
    "n": 5,
    "of": 0.01,
    "res": 60,
    "avg": 1.01,
    "median": 0.97,
    "min": 0.69,
    "max": 1.33,
    "std_dev": 0.3,
    "var": 0.1,
    "sem": 0.13,
    "mse": 0.02,
    "cv": 0.297029702970297,
    "q1": 0.73,
    "q3": 1.31,
    "iqr": 0.5800000000000001,
    "epsg": 4326,
    "longitude": 5.312691,
    "latitude": 60.395897,
    "altitude": 3
},
..
..
..
]

GET /api/data/id/{int: id}/{string: period}/stats/fromutc/{string: fromUtc}/toutc/{string: toUtc}(?exclude=position|none) ¶

Get periodic statistics for sensor using a UTC timestamp range. Date range cannot exceed 2 months.

Outliers are ignored in the calculation.

When ?exclude=position is used in HTTP GET, the aggregation is not performed on distinct sensor positions. Instead the averaged sensor positions are used within the aggregation groups. The aggregation is much slower when not using this filter, especially for moving sensors with a lot of distinct positions.

Parameters:	id (int) – Identifier of sensor period (string) – The period to retrieve statistics for. Accepted value is 'hourly', 'daily', 'weekly' or 'monthly'. fromUtc (string) – UTC start timestamp using the ISO-8601 format toUtc (string) – UTC end timestamp using the ISO-8601 format exclude (string, optional) - Exclude filter during aggregation. Default is none.
Response: JSON Array of Objects:
	id (int) – sensor identifier timestamp_from_epoch (long) – begin timestamp (Unix Epoch) timestamp_to_epoch (long) – end timestamp (Unix Epoch) component (string) – component name level (int) – component data level unit (string) – component unit qc (bool) - quality control flag with two states; 0 or 1. 0: no quality control (component not configured for QC) has been performed on value. 1: quality control has been performed with no outlier flags set. n (int) – sample size of (double) – outlier fraction (OF) of total sample size. Value in interval [0, 1] or -1 when component is not configured for QC. res (int) – original sensor resolution (in seconds) avg (double) – arithmetic average value median (double) – median value (50% percentile) min (double) – minimum value max (double) – maximum value std_dev (double) – standard sample deviation for value var (double) – the variance for value sem (double) – the standard error mean (SEM) for value mse (double) – the mean squared error (MSE) for value cv (double) – the coefficient of variation (CV) for value q1 (double) – first quartile (Q1) ~ 25% percentile q3 (double) – third quartile (Q3) ~ 75% percentile iqr (double) – interquartile range (IQR = Q3 - Q1) epsg (int) – sensor position, SRS code longitude (double) – sensor position, longitude latitude (double) – sensor position, latitude altitude (double) – sensor position, altitude
Status Codes:	400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error

Example request:

GET /api/data/id/117/hourly/stats/fromutc/2020-10-01T09:00:00.00Z/toutc/2020-10-01T10:00:00.00Z HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Bearer bd330e99d8a94a68be975656f45c5a42

Example response:

Please refer to this section.

GET /api/sensors/?? ¶

Get raw sensor data using a UTC timestamp.

Not yet implemented.

Interpretation of quality control (QC) flags ¶

The QC flags are set at raw value level.

Table below displays the possible QC flags:

X = bit not in use

Example: The string representation of the following QC flags "00001011" indicates that a value is repeating (a specified number of times), and also that it is lower than a (specified) minumum value. The numeric value will be 11.

Example: The string representation of the following QC flags "00000000" indicates that QC operations has not been performed for value. The numeric value will be 0.

Example: The string representation of the following QC flags "00000001" indicates that a QC operation has been performed, but no other flags are set. The numeric value will be 1.

Hint: To test whether a specific QC flag is set, the bitwise logical AND operator can be used upon the numeric QC flags value.

Interpretation of specific quality control (QCS) flags ¶

The QCS flags are set at raw value level.

Table below displays the possible QCS flags:

X = bit not in use

Interpretation of quality assurance (QA) flags ¶

Table below displays the possible QA flags:

X = bit not in use

Hint: To test whether a specific QA flag is set, the bitwise logical AND operator can be used upon the numeric QA flags value.

Interpretation of specific quality assurance (QAS) flags ¶

Table below displays the possible QAS flags:

X = bit not in use

Data Disclaimer ¶

NILU makes no warranty of any kind, express or implied, concerning the provided data and information, including but not limited to any warranties of merchantability or fitness for any particular purpose.

NILU assumes no responsibility or legal liability concerning the data’s accuracy, reliability, completeness, timeliness, or usefulness.

GET /api/sensors/{int : id} ¶

Get sensor identified by sensor id.

Parameters:	id (int) – sensor identifier.
Response: JSON Object:
	id (int) – sensor identifier name (string) – sensor name provider (object) sensor provider id (int) – id of provider name (string) – name of provider atom (string) – atom URL to provider description (string) – sensor description resolution (int) – sensor resolution in seconds srs (object) – sensor Spatial Reference System (SRS). More about SRS in this section. epsg (int) – SRS EPSG code srtext (string) – SRS well known text proj4 (string) – SRS description in proj4 format atom (string) – SRS atom URL enabled (boolean) – flag indicating if sensor is enabled for data transfer parameters (array) - Array of Objects (partial Avro Schema) describing the parameters for sensor name (string) – name of parameter type (primitive or object) – type of parameter doc (string) – parameter description (optional) location (object) – sensor location. If sensor is moving (i.e. position is not fixed), then location must explicitly be set to an empty object: {} when configured. Also see this section. longitude (double) – sensor east-west position latitude (double) – sensor north-south position altitude (double) – sensor height above sea level components (array) - Array of Objects describing the components for sensor id (int) – component identifier name (string) – component name binding-path (string) – absolute JSON path to sensor parameter that component is bound to conv_factor (double) - conversion factor (default : 0.0) for component (used in QC pipeline for QC unit conversion). If no conversion algorithm exists for converting current unit into target QC unit, the conv_factor will be set to 0.0 atom (string) – atom URL to component unit (object) – component unit id (int) – unit identifier name (string) – unit name atom (string) – atom URL to unit level (object) – component datalevel. More about datalevels in this section. value (int) – datalevel value description (string) – datalevel description atom (string) – atom URL to datalevel converters (array) - Array of Objects describing the converters used for data transformation. Only required when sensor parameter(s) is not numeric. input-type (primitive) – data type of sensor parameter before transformation output-type (BooleanInteger, StringDouble, StringEpochTime, StringInteger : primitive) – data type of sensor parameter after transformation target-path (string) – absolute JSON path to sensor parameter being converted input-args (object) – input argument(s) for converter. Required or not required depending upon type of converter. atom(string) - atom URL to field converter mapping (array) - Array of Objects describing the field mappers for sensor name (Timestamp : string) – name of field mapper target-path (string) – absolute JSON path to sensor parameter being mapped atom(string) - atom URL to field mapper pipeline (object) – Pipeline flags status flags (int) – Numerical representation of the flags bitflags (string) – Bitwise representation of the flags status (string) – Textual description of the flags atom (string) – atom URL to sensor pipeline status processed (string, UTC, ISO-8601) – Pipeline last processed created (string, UTC, ISO-8601) – date when sensor schema was initially configured updated (string, default: null, UTC, ISO-8601) – date when sensor schema was re-configured atom (string) – atom URL to sensor schema endpoint (string) – target URL to where sensor can push data. If sensor does not have a fixed position (i.e. location), then lon/lat/alt must be injected into the endpoint URL at request time. See example below. Also see this section and this section.
Status Codes:	400 Bad Request 404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/sensors/393 HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "id": 393,
    "name": "Innosense",
    "provider": {
        "id": 1,
        "name": "Norwegian Institute for Air Research",
        "atom": "https://sensors.nilu.no/api/providers/1"
    },
    "resolution": 60,
    "srs": {
        "epsg": 2000,
        "srtext": "PROJCS["Anguilla 1957 / British West Indies Grid",GEOGCS["Anguilla 1957",DATUM["Anguilla_1957",SPHEROID["Clarke 1880 (RGS)",6378249.145,293.465,AUTHORITY["EPSG","7012"]],AUTHORITY["EPSG","6600"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4600"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-62],PARAMETER["scale_factor",0.9995],PARAMETER["false_easting",400000],PARAMETER["false_northing",0],AUTHORITY["EPSG","2000"],AXIS["Easting",EAST],AXIS["Northing",NORTH]]",
        "srtext": "+proj=tmerc +lat_0=0 +lon_0=-62 +k=0.9995000000000001 +x_0=400000 +y_0=0 +ellps=clrk80 +units=m +no_defs ",
        "atom": "https://sensors.nilu.no/api/srs/2000"
    },
    "enabled": true,
    "parameters": [{
        "name": "no2",
        "type": "double",
        "doc": "Predicted NO2 in microgram"
    },
    {
        "name": "date",
        "type": "long",
        "doc": "Date of measurement"
    }],
    "location": 
    {
        "longitude": 67,
        "latitude": 50,
        "altitude": 1.5
    },
    "components": [
    {
        "id": 8,
        "name": "NO2",
        "binding-path": "/no2",
        "conv_factor": 1.0,
        "atom": "https://sensors.nilu.no/api/components/8",
        "unit": {
            "id": 3,
            "name": "µg/m³",
            "atom": "https://sensors.nilu.no/api/units/3"
        },
        "level": {
            "value": 1,
            "description": "Estimate of a geophysical quantity derived from corresponding Level-0 data, using basic physical assumptions and no compensation schemes. Often temporally averaged.",
            "atom": "https://sensors.nilu.no/api/datalevels/1"
        }}
    ],
    "converters": [
    {
        "input-type": "string",
        "output-type": "StringEpochTime",
        "target-path": "/date",
        "input-args": {
            "input-format": "yyyy/MM/dd HH:mm:ss",
            "timezone": "Europe/Stockholm" },
        "atom": "https://sensors.nilu.no/api/doc/converters#StringEpochTime"      
    },
    {
        "input-type": "string",
        "output-type": "StringDouble",
        "target-path": "/no2",
        "atom": "https://sensors.nilu.no/api/doc/converters#StringDouble"      
    }],    
    "mapping": [
    {
        "name": "Timestamp",
        "target-path": "/date",                                                                                                           
        "atom": "https://sensors.nilu.no/api/doc/fieldmapping#Timestamp"
    }],
    "pipeline": 
    {
        "flags": 0,
        "bitflags": "00000000",
        "status": "Never processed",
        "atom": "https://sensors.nilu.no/api/sensors/393/pipeline",
        "processed": null
    },
    "created": "2018-12-17T12:56:23.405806Z",
    "atom": "https://sensors.nilu.no/api/sensors/393",
    "endpoint": "https://sensors.nilu.no/api/sensors/393/inbound"
}

GET /api/sensors ¶

Get a list of sensors.

Response: JSON Array of Objects:
	Please refer to this section.
Status Codes:	500 Internal Server Error error-code (int) – application error

Example request:

GET /api/sensors HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[{
    "id": 393,
    "name": "Innosense",
    "provider": {
        "id": 1,
        "name": "Norwegian Institute for Air Research",
        "atom": "https://sensors.nilu.no/api/providers/1"
    },
    "resolution": 60,
    "srs": {
        "epsg": 2000,
        "srtext": "PROJCS["Anguilla 1957 / British West Indies Grid",GEOGCS["Anguilla 1957",DATUM["Anguilla_1957",SPHEROID["Clarke 1880 (RGS)",6378249.145,293.465,AUTHORITY["EPSG","7012"]],AUTHORITY["EPSG","6600"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4600"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-62],PARAMETER["scale_factor",0.9995],PARAMETER["false_easting",400000],PARAMETER["false_northing",0],AUTHORITY["EPSG","2000"],AXIS["Easting",EAST],AXIS["Northing",NORTH]]",
        "srtext": "+proj=tmerc +lat_0=0 +lon_0=-62 +k=0.9995000000000001 +x_0=400000 +y_0=0 +ellps=clrk80 +units=m +no_defs ",
        "atom": "https://sensors.nilu.no/api/srs/2000"
    },
    "enabled": true,
    "parameters": [{
        "name": "no2",
        "type": "double",
        "doc": "Predicted NO2 in microgram"
    },
    {
        "name": "date",
        "type": "long",
        "doc": "Date of measurement"
    }],
    "location": 
    {
        "longitude": 67,
        "latitude": 50,
        "altitude": 1.5
    },
    "components": [
    {
        "id": 8,
        "name": "NO2",
        "binding-path": "/no2",
        "conv_factor": 1.0,
        "atom": "https://sensors.nilu.no/api/components/8",
        "unit": {
            "id": 3,
            "name": "µg/m³",
            "atom": "https://sensors.nilu.no/api/units/3"
        },
        "level": {
            "value": 1,
            "description": "Estimate of a geophysical quantity derived from corresponding Level-0 data, using basic physical assumptions and no compensation schemes. Often temporally averaged.",
            "atom": "https://sensors.nilu.no/api/datalevels/1"
        }}
    ],
    "converters": [
    {
        "input-type": "string",
        "output-type": "StringEpochTime",
        "target-path": "/date",
        "input-args": {
            "input-format": "yyyy/MM/dd HH:mm:ss",
            "timezone": "Europe/Stockholm" },
        "atom": "https://sensors.nilu.no/api/doc/converters#StringEpochTime"      
    },
    {
        "input-type": "string",
        "output-type": "StringDouble",
        "target-path": "/no2",
        "atom": "https://sensors.nilu.no/api/doc/converters#StringDouble"      
    }],    
    "mapping": [
    {
        "name": "Timestamp",
        "target-path": "/date",                                                                                                           
        "atom": "https://sensors.nilu.no/api/doc/fieldmapping#Timestamp"
    }],
    "pipeline": 
    {
        "flags": 0,
        "bitflags": "00000000",
        "status": "Never processed",
        "atom": "https://sensors.nilu.no/api/sensors/393/pipeline",
        "processed": null
    },
    "created": "2018-12-17T12:56:23.405806Z",
    "atom": "https://sensors.nilu.no/api/sensors/393",
    "endpoint": "https://sensors.nilu.no/api/sensors/393/inbound"
},
{
    "id": 394,
    "name": "HackAir",
    "provider": {
        "id": 1,
        "name": "Norwegian Institute for Air Research",
        "atom": "https://sensors.nilu.no/api/providers/1"
    },
    "resolution": 3600,
    "srs": {
        "epsg": 4326,
        "srtext": "GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4326"]]",
        "srtext": "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ",
        "atom": "https://sensors.nilu.no/api/srs/4326"
    }    ,
    "enabled": true,
    "parameters": [
    {
        "name": "temperature",
        "type": "double",
        "doc": "Ground temperature"
    },
    {
        "name": "PM10",
        "type": "double",
        "doc": "Particulate matter. 10 micrometers or less in diameter."
    }],
    "location": null,           
    "components": [
    {
        "id": 15,
        "name": "Temperature",
        "binding-path": "/temperature",
        "conv_factor": 0.0,
        "atom": "https://sensors.nilu.no/api/components/15",
        "unit": {
            "id": 8,
            "name": "K",
            "atom": "https://sensors.nilu.no/api/units/8"
        },
        "level": {
            "value": 1,
            "description": "Estimate of a geophysical quantity derived from corresponding Level-0 data, using basic physical assumptions and no compensation schemes. Often temporally averaged.",
            "atom": "https://sensors.nilu.no/api/datalevels/1"
        }},
    {
        "id": 12,
        "name": "PM10",
        "binding-path": "/pm10",
        "conv_factor": 1.0,
        "atom": "https://sensors.nilu.no/api/components/12",
        "unit": {
            "id": 3,
            "name": "µg/m³",
            "atom": "https://sensors.nilu.no/api/units/3"
        },
        "level": {
            "value": 1,
            "description": "Estimate of a geophysical quantity derived from corresponding Level-0 data, using basic physical assumptions and no compensation schemes. Often temporally averaged.",
            "atom": "https://sensors.nilu.no/api/datalevels/1"
        }}
    ],
    "converters": [
    {
        "input-type": "string",
        "output-type": "StringDouble",
        "target-path": "/temperature",
        "atom": "https://sensors.nilu.no/api/doc/converters#StringDouble"      
    },
    {
        "input-type": "string",
        "output-type": "StringDouble",
        "target-path": "/pm10",
        "atom": "https://sensors.nilu.no/api/doc/converters#StringDouble"      
    }],    
    "mapping": null,
    "pipeline": 
    {
        "flags": 10,
        "bitflags": "00001010",
        "status": "Raw data processed and stored. QA/QC executed.",
        "atom": "https://sensors.nilu.no/api/sensors/394/pipeline",
        "processed": "2020-09-08T18:05:32.0000000Z"
    },    
    "created": "2018-12-18T12:50:23.405806Z",
    "atom": "https://sensors.nilu.no/api/sensors/394",
    "endpoint": "https://sensors.nilu.no/api/sensors/394/{longitude}/{latitude}/{altitude}/inbound"
}]

GET /api/sensors/{int : id}/components ¶

Get a list of components configured for sensor given id of sensor.

Parameters:	id (int) – sensor identifier.
Response: JSON Array of Objects:
	id (int) – component identifier name (string) – component name binding-path (string) – absolute JSON path to sensor parameter that component is bound to conv_factor (double) - conversion factor (default : 0.0) for component (used in QC pipeline for QC unit conversion). If no conversion algorithm exists for converting current unit into target QC unit, the conv_factor will be set to 0.0 atom (string) – atom URL to component unit (object) – component unit id (int) – unit identifier name (string) – unit name atom (string) – atom URL to unit level (object) – component datalevel. More about datalevels in this section. value (int) – datalevel value description (string) – datalevel description atom (string) – atom URL to datalevel
Status Codes:	404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/sensors/234/components HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[{
    "id": 84,
    "name": "PM10",
    "type": "Standard",
    "atom": "https://sensors.nilu.no/api/components/84"    
},
{
    "id": 64,
    "name": "NO2",
    "type": "Standard",
    "atom": "https://sensors.nilu.no/api/components/64"    
}]

GET /api/sensors/{int : id}/converters ¶

Get a list of converters configured for sensor given id of sensor.

Parameters:	id (int) – sensor identifier.
Response: JSON Array of Objects:
	input-type (primitive) – data type of sensor parameter before transformation output-type (BooleanInteger, StringDouble, StringEpochTime, StringInteger : primitive) – data type of sensor parameter after transformation target-path (string) – absolute JSON path to sensor parameter being converted input-args (object) – input argument(s) for converter. Required or not required depending upon type of converter. atom(string) - atom URL to field converter
Status Codes:	404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/sensors/234/converters HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[
    {
        "input-type": "string",
        "output-type": "StringEpochTime",
        "target-path": "/date",
        "input-args": {
            "input-format": "yyyy/MM/dd HH:mm:ss",
            "timezone": "Europe/Stockholm" },
        "atom": "https://sensors.nilu.no/api/doc/converters#StringEpochTime"      
    },
    {
        "input-type": "string",
        "output-type": "StringDouble",
        "target-path": "/no2",
        "atom": "https://sensors.nilu.no/api/doc/converters#StringDouble"      
    }
]

GET /api/sensors/{int : id}/mapping ¶

Get a list of field mappers configured for sensor given id of sensor.

Parameters:	id (int) – sensor identifier.
Response: JSON Array of Objects:
	name (Timestamp : string) – name of field mapper target-path (string) – absolute JSON path to sensor parameter being mapped atom(string) - atom URL to field mapper
Status Codes:	404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/sensors/224/mapping HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[
    {
        "name": "Timestamp",
        "target-path": "/date",                                                                                                           
        "atom": "https://sensors.nilu.no/api/doc/fieldmapping#Timestamp"
    }
]

GET /api/sensors/{int : id}/location ¶

Get the sensor location given id of sensor.

Parameters:	id (int) – sensor identifier.
Response: JSON Object:
	longitude (double) – sensor east-west position latitude (double) – sensor north-south position altitude (double) – sensor height above sea level
Status Codes:	404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/sensors/224/location HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
                    "longitude": 67.0,
                    "latitude": 50.0,
                    "altitude": 1.5
}

Note: If location is not configured for sensor, an empty JSON object ({ }) will be the response from server.

GET /api/sensors/{int : id}/parameters ¶

Get the parameters configured for sensor given id of sensor.

Parameters:	id (int) – sensor identifier.
Response: JSON Array of Objects (partial Avro Schema):
	name (string) – name of parameter type (primitive or object) – type of parameter doc (string) – parameter description (optional)
Status Codes:	404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/sensors/234/parameters HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[
    {
        "name": "temperature",
        "type": "double",
        "doc": "Ground temperature"
    },
    {
        "name": "PM10",
        "type": "double",
        "doc": "Particulate matter. 10 micrometers or less in diameter."
    }
]

POST /api/sensors/configure ¶

New sensor schema configuration.

Parameters:	name (string) – sensor name (required) description (string) – sensor description resolution (int) – sensor resolution in seconds (required) srs (object) – sensor Spatial Reference System (SRS). More about SRS in this section. epsg (int) – SRS EPSG code enabled (boolean) – flag indicating if sensor is enabled for data transfer (default: true) parameters (array) - Array of Objects (partial Avro Schema) describing the parameters for sensor (required) name (string) – name of parameter type (primitive or object) – type of parameter doc (string) – parameter description (optional) location (object) – sensor location. If sensor is moving (i.e. position is not fixed), then location must explicitly be set to an empty object: {} when configured. Also see this section. longitude (double) – sensor east-west position latitude (double) – sensor north-south position altitude (double) – sensor height above sea level components (array) - Array of Objects describing the components for sensor (required) componentid (int) – component identifier unitid (int) – unit identifier binding-path (string) – absolute JSON path to sensor parameter that component is bound to. More about binding paths in this section. level (int) – component datalevel (required). More about datalevels in this section. converters (array) - Array of Objects describing the converters used for data transformation. Only required when sensor parameter(s) is not numeric. input-type (primitive) – data type of sensor parameter before transformation output-type (BooleanInteger, StringDouble, StringEpochTime, StringInteger : primitive) – data type of sensor parameter after transformation target-path (string) – absolute JSON path to sensor parameter being converted input-args (object) – input argument(s) for converter. Required or not required depending upon type of converter. mapping (array) - Array of Objects describing the field mappers for sensor name (Timestamp : string) – name of field mapper target-path (string) – absolute JSON path to sensor parameter being mapped
Request: JSON Object
Response: JSON Object:
	sensorid (int) – sensor identifier message (string) – HTTP status text http-status-code (int) – HTTP status code atom (string) – atom URL to sensor
Status Codes:	400 Bad Request 401 Unauthorized 500 Internal Server Error error-code (int) – application error 100 - sensor pool full 112 - an error occured while publishing sensor schema to backend system 115 - invalid parameter schema 124 - parameter misconfiguration 129 - invalid parameter path 130 - invalid converter arguments 132 - invalid timezone 220 - component not found in system 225 - datalevel not found in system 226 - unknown EPSG code (srid) 230 - unit not found in system 300 - communication error with backend system 305 - an error occured while transfering data to backend system 410 - name conflict 500 - not authorized

Example request:

POST /api/sensors/configure HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Content-Type: application/json
Authorization: Bearer 9a0ddc7b7aaa47d3973529a5f2d16fef
{
    "name": "Innosense",
    "description": "Innosense sensor",
    "resolution": 60,
    "srs": {
        "epsg": 4326        
    },
    "enabled": true,    
    "location":
    {
        "longitude": 67,
        "latitude": 50,
        "altitude": 1.5
    },
    "parameters": [
    {
        "name": "no2",
        "type": "double",
        "doc": "Predicted NO2 in microgram"
    },
    {
        "name": "date",
        "type": "long",
        "doc": "Date of measurement"
    }]
    ,    
    "components": [
    {
        "componentid": 64,
        "unitid": 35,
        "binding-path": "/no2"
        "level": 1
    }]
    ,    
    "converters": [
    {
        "input-type": "string",
        "output-type": "StringEpochTime",
        "target-path": "/date",
        "input-args": {
            "input-format": "yyyy/MM/dd HH:mm:ss",
            "timezone": "Europe/Stockholm" }
    },
    {
        "input-type": "string",
        "output-type": "StringDouble",
        "target-path": "/no2"
    }]
    ,    
    "mapping": [
    {
        "name": "Timestamp",
        "target-path": "/date"
    }]
}

Example response:

HTTPS/1.1 201 OK
Content-Type: application/json
{
    "sensorid": 421,
    "message": "Created",
    "http-status-code": 201
    "atom": "https://sensors.nilu.no/api/sensors/421"
}

PUT /api/sensors/{int : id}/reconfigure ¶

Reconfigures existing sensor schema identified by id.

Sensor must be disabled before re-configuration is possible. Please refer to this section.

Parameters:	id (int) – sensor identifier
Request: JSON Object
	name (string) – sensor name (optional) description (string) – sensor description (optional) resolution (int) – sensor resolution in seconds (optional) srs (object) – sensor Spatial Reference System (SRS, optional) enabled (boolean) – flag indicating if sensor is enabled for data transfer (optional) parameters (array) - Array of Objects (partial Avro Schema) describing the parameters for sensor (optional) location (object) – sensor location. If location of sensor is not fixed, then location must explicitly be set to an empty object:"location": {}. Also see this section (optional) components (array) - Array of Objects describing components for sensor (optional) converters (array) - Array of Objects describing converters used for data transformation. Only required when sensor parameter(s) is not numeric (optional) mapping (array) - Array of Objects describing field mappers for sensor (optional)
Response: JSON Object:
	sensorid (int) – sensor identifier message (string) – HTTP status text http-status-code (int) – HTTP status code atom (string) – atom URL to sensor
Status Codes:	400 Bad Request 401 Unauthorized 500 Internal Server Error error-code (int) – application error 100 - sensor pool full 112 - an error occured while publishing sensor schema to backend system 115 - invalid parameter schema 124 - parameter misconfiguration 129 - invalid parameter path 130 - invalid converter arguments 132 - invalid timezone 220 - component not found in system 225 - datalevel not found in system 226 - unknown EPSG code (srid) 230 - unit not found in system 300 - communication error with backend system 305 - an error occured while transfering data to backend system 410 - name conflict 500 - not authorized 401 - sensor enabled

Example request:

PUT /api/sensors/123/reconfigure HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Content-Type: application/json
Authorization: Bearer fb2c10069cd7411395806f1fc865fc89
{
    "name": "Innosense_new",
    "description": "Innosense sensor",
    "resolution": 20,
    "srs": {
        "epsg": 4326        
    },
    "enabled": true,    
    "location":
    {
        "longitude": 32,
        "latitude": 76,
        "altitude": 1
    }}

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "sensorid": 123,
    "message": "OK",
    "http-status-code": 200
    "atom": "https://sensors.nilu.no/api/sensors/123"
}

The "binding-path" and "target-path" JSON attributes are used when a converter or a field mapper is used when defining the sensor schema.

When defining a new sensor schema and specifying the components, the binding-path is the absolute JSON path to an attribute (in sensor data packet) that will be "bound" to a component (eg. PM₁₀, NO₂, CO).

Similar, when using a converter (if required) for one of the components defined using the binding-path, the converter takes the target-path as an argument. The converter requires this path in order to be able to convert an attribute (k) with value (v) located at the given JSON path.

Same principle applies when using a field mapper. The field mapper m is an alias for attribute k with value v located at target path p.

These attributes supports JPath syntax.

Below is a table with some examples:

{ "no2" : 15.232 }

{ "no2" : { "value" : 15.232 }}

{ "gas" : { "components" : [ { "no2" : { "value" : 15.232 } }, .. , { "no2" : { "value" : 15.232 } } ] }}

{ "level1" : { "lev.el2" : { "no2" : { "value" : 15.232 } } } }

POST /api/sensors/{int : id}/disable ¶

Puts the sensor in disabled mode using the sensor id.

Parameters:	id (int) – sensor identifier.
Response: JSON Object:
	sensorid (int) – sensor identifier message (string) – HTTP status text http-status-code (int) – HTTP status code
Status Codes:	401 Unauthorized 404 Not Found 500 Internal Server Error error-code (int) – application error 120 - an error occured on schema server 300 - communication error with backend system 305 - an error occured while transfering data to backend system 500 - not authorized

Example request:

POST /api/sensors/393/disable HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Bearer 72e896526d5447a8a892014f62d1b21c

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "sensorid": 393,
    "message": "OK",
    "http-status-code": 200
}

DELETE /api/sensors/{int : id}/delete ¶

Deletes sensor identified by id.

Sensor must be in disabled state prior to delete operation. Please refer to this section.

Existing data in storage system will not be deleted.

Parameters:	id (int) – sensor identifier.
Response: JSON Object:
	sensorid (int) – sensor identifier message (string) – HTTP status text http-status-code (int) – HTTP status code
Status Codes:	401 Unauthorized 500 Internal Server Error error-code (int) – application error 120 - an error occured on schema server 300 - communication error with backend system 305 - an error occured while transfering data to backend system 401 - sensor enabled 500 - not authorized 510 - authorized, but no access

Example request:

DELETE /api/sensors/393/delete HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Authorization: Basic NDQwNTU3NGFhZGM1NDY0OjA1ZWEzZWRiNjg=

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "sensorid": 393,
    "message": "OK",
    "http-status-code": 200
}

GET /api/datalevels ¶

Get a list of available datalevels.

The datalevel is set on sensor component during configuration.

Response: JSON Array of Objects:
	value (int) – datalevel value description (string) – datalevel description atom (string) – atom URL to datalevel
Status Codes:	500 Internal Server Error error-code (int) – application error

Example request:

GET /api/datalevels HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[{
    "value": 1,
    "description": "Estimate of a geophysical quantity derived from corresponding Level-0 data, using basic physical assumptions and no compensation schemes. Often temporally averaged.",
    "atom": "https://sensors.nilu.no/api/datalevels/1"
},
{
    "value": 2,
    "description": "Estimate of a geophysical quantity using any available data within the sensor system itself. Often temporally averaged.",
    "atom": "https://sensors.nilu.no/api/datalevels/2"
}]

GET /api/datalevels/{int : level} ¶

Get datalevel identified by value.

Parameters:	level (int) – Datalevel value.
Response: JSON object:
	value (int) – datalevel value description (string) – datalevel description atom (string) – atom URL to datalevel
Status Codes:	404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/datalevels/1 HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "value": 1,
    "description": "Estimate of a geophysical quantity derived from corresponding Level-0 data, using basic physical assumptions and no compensation schemes. Often temporally averaged.",
    "atom": "https://sensors.nilu.no/api/datalevels/1"
}

POST /api/sensors/{int : id}/inbound ¶

Data transfer using fixed sensor position.

Parameters:	id (int) – sensor identifier.
Request: JSON Object
Response: JSON Object:
	atom (string) – atom URL to sensor pipeline status message (string) – HTTP status text http-status-code (int) – HTTP status code
Status Codes:	400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error error-code (int) – application error 110 - sensor data is not valid according to declared schema 131 - an error occured during parameter conversion 300 - communication error with backend system 305 - an error occured while transfering data to backend system 400 - sensor disabled 500 - not authorized

Example request:

POST /api/sensors/393/inbound HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Content-Type: application/json
Authorization: Bearer 1b9d1bc16ac64995ab3d1775b476f90e
{
    "sensorid": "innosense-6",
    "date": "2010/10/20 15:00:00",
    "position": [
        "0.000000",
        "0.000000"
    ],
    "rawvalues": [
        "fff98ea8",
        "000296f6"
        ..
        ..
        ..
    ],
    "samplecount": "40",
    "viewer_wanip": "37.253.165.85",
    "scanner_wanip": "37.253.165.85",
    "regulator": [
        "16.54",
        "22.93"
        ..
        ..
        ..
    ],
    "no2": "132.5657676765"
}

Note: Only date and NO₂ parameters are configured in example above. The date parameter is mapped as timestamp, and the NO₂ parameter is mapped as component with a corresponding unit in the backend system. The other parameters are ignored, but stored as raw data, when sensor data is processed (see section above). The parameter sensorid should not be confused with the sensorid in API documentation because sensorid is an internal id used by the sensor vendor in example above.

Also note: When data is in the XML format, the Content-Type request header must be set to application/xml.

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json

{
    "atom": "https://sensors.nilu.no/api/sensors/393/pipeline",
    "message": "OK",
    "http-status-code": 200
}

POST /api/sensors/{int : id}/{double : longitude}/{double : latitude}/{double : altitude}/inbound ¶

Data transfer using GPS enabled sensors.

Parameters:	id (int) – sensor identifier. longitude (double) – east-west position of sensor latitude (double) – north-south position of sensor altitude (double) – sensor height above sea level
Request: JSON Object
Response: JSON Object:
	atom (string) – atom URL to sensor pipeline status message (string) – HTTP status text http-status-code (int) – HTTP status code
Status Codes:	300 Multiple Choices - sensor configured with fixed location. HTTP response header parameter endpoint contains correct endpoint URL. 400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error error-code (int) – application error 110 - sensor data is not valid according to declared schema 131 - an error occured during parameter conversion 300 - communication error with backend system 305 - an error occured while transfering data to backend system 400 - sensor disabled 500 - not authorized

Example request:

POST https://sensors.nilu.no/api/sensors/394/60/50/1/inbound HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json
Content-Type: application/json
Authorization: Bearer 0806ada4507449648c85f0a376c5c447
{
    "name": "HackAir",
    "temperature": "24.61",
    "humidity": "50.12",
    "pm25": "412.77",
    "pm10": "804.34",
    "freemembytes": "1024"
}

Note: Only temperature and PM₁₀ parameters are configured in example above and these are the only parameters that will be mapped as components. The other parameters are ignored, but stored as raw data, when data is processed (see section above). Also note that this sample sensor does not contain any timestamp parameter, therefore no timestamp mapping is possible here. In this example the system time will be used as timestamp for data.

Also note: When data is in the XML format, the Content-Type request header must be set to application/xml.

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json

{
    "atom": "https://sensors.nilu.no/api/sensors/394/pipeline",
    "message": "OK",
    "http-status-code": 200
}

POST /api/sensors/{int : id}/inbound/?pushtest=true ¶

Test data transfer using fixed sensor position.

No data will be stored during push-test.

Example request:

Please refer to this section.

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json

{
    "atom": "https://sensors.nilu.no/api/sensors/393/pipeline/test",
    "message": "OK",
    "http-status-code": 200
}

POST /api/sensors/{int : id}/{double : longitude}/{double : latitude}/{double : altitude}/inbound/?pushtest=true ¶

Test data transfer using GPS enabled sensors.

No data will be stored during push-test.

Example request:

Please refer to this section.

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json

{
    "atom": "https://sensors.nilu.no/api/sensors/394/pipeline/test",
    "message": "OK",
    "http-status-code": 200
}

GET /api/components ¶

Get a list of available components.

Response: JSON Array of Objects:
	id (int) – component identifier name (string) – component name type (string) – component type description (string, optional) – component description atom (string) – atom URL to component
Status Codes:	500 Internal Server Error error-code (int) – application error

Example request:

GET /api/components HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[{
    "id": 84,
    "name": "PM10",
    "type": "Standard",
    "atom": "https://sensors.nilu.no/api/components/84"    
},
{
    "id": 64,
    "name": "NO2",
    "type": "Standard",
    "atom": "https://sensors.nilu.no/api/components/64"    
}]

GET /api/components/{int : id} ¶

Get component identified by component id.

Parameters:	id (int) – Identifier of component.
Response: JSON object:
	id (int) – component identifier name (string) – component name type (string) – component type description (string, optional) – component description atom (string) – atom URL to component
Status Codes:	400 Bad Request 404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/components/84 HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "id": 84,
    "name": "PM10",
    "type": "Standard",
    "atom": "https://sensors.nilu.no/api/components/84"    
}

GET /api/units ¶

Get a list of available units.

Response: JSON Array of Objects:
	id (int) – unit identifier name (string) – unit name atom (string) – atom URL to unit
Status Codes:	500 Internal Server Error error-code (int) – application error

Example request:

GET /api/units HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[{
    "id": 3,
    "name": "µg/m³",
    "atom": "https://sensors.nilu.no/api/units/3"
},
{
    "id": 8,
    "name": "K",
    "atom": "https://sensors.nilu.no/api/units/8"
}]

GET /api/units/{int : id} ¶

Get unit identified by unit id.

Parameters:	id (int) – Identifier of unit.
Response: JSON object:
	id (int) – unit identifier name (string) – unit name atom (string) – atom URL to unit
Status Codes:	400 Bad Request 404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/units/3 HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "id": 3,
    "name": "µg/m³",
    "atom": "https://sensors.nilu.no/api/units/3"
}

Timestamps ¶

It is possible to map a JSON attribute representing a moment in time as a timestamp when storing data.

If this JSON attribute is given as number of seconds since 00:00:00 UTC on 1 January 1970 (Unix Epoch) , then no timestamp converter is required.

On the other hand, if the attribute is represented as a string of any given format (e.g. 'yyyy/MM/dd HH:mm:ss'), then the StringEpochTime converter must be used. This converter converts the string value into Unix Epoch.

In both cases the Timestamp Mapper must be used in order to tell the system that you want to use the JSON attribute as a timestamp. If this attribute mapping is omitted, the system time will instead be used.

GET /api/timezones ¶

Get a list of available timezones.

Response: JSON Array of Objects:
	timezone (string) – timezone identifier supportsDaylightSavingTime (boolean) – boolean value indicating if the time zone has any daylight saving time rules
Status Codes:	500 Internal Server Error error-code (int) – application error

Example request:

GET /api/timezones HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[{
    "timezone": "Europe/Stockholm",
    "supportsDaylightSavingTime": true   
},
..
..
..
{
    "timezone": "America/Chicago",
    "supportsDaylightSavingTime": true   
}]

GET /api/srs ¶

Get a list of available Spatial Reference Systems (SRS).

Response: JSON Array of Objects:
	epsg (int) – SRS EPSG code srtext (string) – SRS well known text proj4 (string) – SRS description in proj4 format atom (string) – SRS atom URL
Status Codes:	500 Internal Server Error error-code (int) – application error

Example request:

GET /api/srs HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
[{
    "epsg": 2000,
    "srtext": "PROJCS["Anguilla 1957 / British West Indies Grid",GEOGCS["Anguilla 1957",DATUM["Anguilla_1957",SPHEROID["Clarke 1880 (RGS)",6378249.145,293.465,AUTHORITY["EPSG","7012"]],AUTHORITY["EPSG","6600"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4600"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-62],PARAMETER["scale_factor",0.9995],PARAMETER["false_easting",400000],PARAMETER["false_northing",0],AUTHORITY["EPSG","2000"],AXIS["Easting",EAST],AXIS["Northing",NORTH]]",
    "srtext": "+proj=tmerc +lat_0=0 +lon_0=-62 +k=0.9995000000000001 +x_0=400000 +y_0=0 +ellps=clrk80 +units=m +no_defs ",
    "atom": "https://sensors.nilu.no/api/srs/2000"
},
..
..
..
..
..
{
    "epsg": 4326,
    "srtext": "GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4326"]]",
    "srtext": "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ",
    "atom": "https://sensors.nilu.no/api/srs/4326"
}]

GET /api/srs/{int : srid} ¶

Get a Spatial Reference System (SRS) identified by srid.

Parameters:	srid (int) – Spatial Reference System (SRS) identifier (i.e. EPSG code).
Response: JSON Object:
	epsg (int) – SRS EPSG code srtext (string) – SRS well known text proj4 (string) – SRS description in proj4 format atom (string) – SRS atom URL
Status Codes:	400 Bad Request 404 Not Found 500 Internal Server Error error-code (int) – application error

Example request:

GET /api/srs/4326 HTTPS/1.1
Host: https://sensors.nilu.no
Accept: application/json

Example response:

HTTPS/1.1 200 OK
Content-Type: application/json
{
    "epsg": 4326,
    "srtext": "GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4326"]]",
    "srtext": "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ",
    "atom": "https://sensors.nilu.no/api/srs/4326"
}

Avro Schema ¶

Apache Avro is used to define the data schema to the value of a record. A record value in this context is the sensor data ("packet") itself. The schema describes the fields allowed in the value, along with their expected data types.

The parameter schema for sensor (described in other sections in this document) is defined as a partial Avro schema. It is defined as partial because it is not complete until created in backend system during sensor schema configuration or reconfiguration.

Avro schema combined with the sensor data defines the "Avro record". This record is transmitted to backend system for further processing and storage.

The usage of Avro schemas allows serialized values to be stored in a very space-efficient binary format (Avro encoded format).

More information about the Avro API can be found here (external page).

Interpretation of the pipeline status flags ¶

The pipeline status flags are set at the sensor level.

Table below displays the possible pipeline flag values:

X = bit not in use

Example: The string representation of the following pipeline flags "00001010" indicates that inbound data has been processed, and that data has been going through the quality control pipeline. The numeric value will be 10.

Example: The string representation of the following pipeline flags "00000000" indicates that sensor data has never been processed, neither in the inbound nor in the QC pipeline. The numeric value will be 0.

Example: The string representation of the following pipeline flags "00000010" indicates that inbound data has been processed, but with no quality control. The numeric value will be 2.

Example: The string representation of the following pipeline flags "00010010" indicates that inbound data has been processed, but that the processing of data has failed in the QC pipeline. The numeric value will be 18.

Example: The string representation of the following pipeline flags "00000001" indicates that inbound data has been processed, but with no data (*). The numeric value will be 1.

(*) The "no data" pipeline flag is set if all sensor components in data packet are containing NaN values.

Hint: In order to test whether a specific pipeline flag is set, the bitwise logical AND operator can be used upon the numeric pipeline "flags" value.

Errors ¶

All API endpoints use a standard error message format for any requests that return an HTTP status indicating an error (any 400 or 500 statuses). For example, a request entity that omits a required field may generate the following response:

HTTPS/1.1 422 Unprocessable Entity
Content-Type: application/json

{    
    "error-code": 1000,
    "error-message": "Sensor name must be defined.",
    "http-status-code": 422
}

Although it is good practice to check the status code, you may safely parse the response of the API calls and check for the presence of an error-code field to detect errors.

Some error codes are used frequently across the entire API and you will probably want to have general purpose code to handle these, whereas most other error codes will need to be handled on a per-request basis.