Read API Documentation

This document describes the usage of the Megasense Read API, used for listing sensors and accessing their data.

Listing keys (sensors)

You need to know the project (bucket) you are interested in to list all the keys (sensors) that belong to it. You get access to one or more buckets when you apply for credentials on the landing page.


curl --header "Content-Type: application/json" -d \
  '{"accessKey": "secret, ask someone for this"}' \
  https://megasense-server.cs.helsinki.fi/read/v3/listKeys/aqdata-urbansense

Will return the following JSON:

Listing data items (sensor messages)

You need to know the sensor you are interested in, and have an idea of when the data was recorded, to access its data. the `154` in the example refers to a unix timestamp prefix, meaning between `1540000000` and `1549999999` (Saturday 20.10.2018 01:46:40 UTC and Tuesday 12.2.2019 19:33:19 UTC). You can use the unix date command to figure out what you want. Note that using just "1" will give you all data from the year 2001 until the year 2033, which should be good enough for now.

Date usage help:


$ date -u -d @1549999999

ti 12.2.2019 19.33.19 +0000

$ date -u -d @1540000000

la 20.10.2018 01.46.40 +0000

$ date -d "2019-02-13" +%s

1550008800

Usage example:


curl --header "Content-Type: application/json" -d \
  '{"accessKey": "secret, ask someone for this"}' \
  https://megasense-server.cs.helsinki.fi/read/v3/listJson/aqdata-urbansense/microsmear_smear/154

will return:


["aqdata-urbansense/microsmear_smear/1549573374833.jsonl",
 "aqdata-urbansense/microsmear_smear/1549573358475.jsonl",
 "aqdata-urbansense/microsmear_smear/1549573342130.jsonl",
 "aqdata-urbansense/microsmear_smear/1549573260769.jsonl",
 "aqdata-urbansense/microsmear_smear/1549573325816.jsonl",
 "aqdata-urbansense/microsmear_smear/1549573293425.jsonl",
 "aqdata-urbansense/microsmear_smear/1549573309461.jsonl",
 "aqdata-urbansense/microsmear_smear/1549573277121.jsonl"]

Reading an item

To read an item, you need to know its exact path. Refer to the examples above for how to list items.


curl --header "Content-Type: application/json" -d \
  '{"accessKey": "secret, ask someone for this"}' \
  https://megasense-server.cs.helsinki.fi/read/v3/download/aqdata-urbansense/microsmear_smear/1549573374833.jsonl

will return:

{"data":{"timestamp":1549573374833,"ccs811-co2":400},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"ccs811-tvoc":0},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"ccs811-temp":25.0,"timestamp":1549573374833},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"shiney-pm10":2},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"mq9-co":1},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"mq131-o3":29},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"cjcmu4541-red":270},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"cjcmu4541-no2":652},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"bme280-temp":27.3068359375},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"bme280-hum":29.629725180693516},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"bme280-press":1009.3488493472992},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}
{"data":{"timestamp":1549573374833,"bme280-alt":109.8312415090365},"receivedTimestamp":1549573375558,"key":"microsmear_smear/1549573374833"}

Reading multiple items at once (with optional filtering)

You need to know the key to read data under it. The above call can be used for that. Usage example:


curl --header "Content-Type: application/json" -d \
  '{"accessKey": "secret, ask someone for this", "from": 1549972866864, "to": 1549972890000}' \
  https://megasense-server.cs.helsinki.fi/read/v3/download/aqdata-urbansense/microsmear_smear

will return:

[{"data":{"ccs811-co2":776,"timestamp":1549972866864},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"ccs811-tvoc":57,"timestamp":1549972866864},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"ccs811-temp":29.76747075179776,"timestamp":1549972866864},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"shiney-pm10":592,"timestamp":1549972866864},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"mq9-co":0,"timestamp":1549972866864},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"timestamp":1549972866864,"mq131-o3":17},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"cjcmu4541-red":241,"timestamp":1549972866864},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"cjcmu4541-no2":507,"timestamp":1549972866864},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"timestamp":1549972866864,"bme280-temp":9.5357421875},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"bme280-hum":35.7305915896018,"timestamp":1549972866864},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"timestamp":1549972866864,"bme280-press":1003.3406908044494},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
{"data":{"bme280-alt":159.9109642443987,"timestamp":1549972866864},"receivedTimestamp":1549972867671,"key":"microsmear_smear/1549972866864"}
]

Site Map Contact Us Terms and Conditions Privacy Policy

MegaSense API

Read API Documentation

Listing keys (sensors)

Listing data items (sensor messages)

Reading an item

Reading multiple items at once (with optional filtering)