Skip to content

EN APIs

Jump to bottom Edit New page
Nils Tjaden edited this page May 4, 2023 · 21 revisions

Change language: DE

next page: Pinouts NodeMCU v2, v3

Accessing the API data

We have some API endpoints to access the sensor data using GET requests and no credentials. The endpoints are covered here.

Domains

API sensor.community (aka dusti.api, formerly known as Luftdaten.info)

The API accepts the sensor data and serves as a basis for the graphical representation on https://maps.sensor.community/ . In addition, the data from the "public" sensors is exported as CSV once a day (around 8:00 am) and made available at http://archive.sensor.community/.

API Madavi.de

The API also receives the sensor data and saves it in a CSV file (one file per sensor and day). Furthermore, the data is stored in an InfluxDB database and graphically processed via Grafana. The file archive can be accessed at https://api-rrd.madavi.de/csvfiles.php, the graphical representation at https://api-rrd.madavi.de/grafana/d/GUaL5aZMz/pm-sensors?orgId=1 .

API sensor.comunity

There are two domains where the same data is served.

  • https://api.sensor.community - This is optimized for receiving data. DON'T use this to request data.
  • https://data.sensor.community - This is faster and more reliable for serving data, so should be used for reporting cases. Where it is not supported for a certain endpoint, the previous domain must be used.

Update frequency

For performance reasons, data is not immediately available.

An endpoint covering data in the last minute is updated every minute. While an endpoint covering data for the last 24 hours is updated every 5 minutes.

Endpoints

V1
  • https://data.sensor.community/static/v1/data.json - all measurements of the last 5 minutes for all sensors.
  • https://data.sensor.community/airrohr/v1/filter/{query} - all measurements of the last 5 minutes filtered by query
    • type={sensor type} : comma-separated list of sensor types, e.g. SDS011,BME280
    • area={lat,lon,distance} : all sensors within a max radius e.g. 52.5200,13.4050,10 (Berlin)
    • box={lat1,lon1,lat2,lon2} : all sensors in a 'box' with the given coordinates e.g. 52.1,13.0,53.5,13.5
    • country={country code} : comma-separated list of country codes. Example BE,DE,NL

Important: The client needs to send a user agent header. In the best case the user agent string should give us a chance to contact the source of i.e. excessive requests. (since 2022/11/04)

  • https://data.sensor.community/airrohr/v1/sensor/{apiID}/ - all measurements of the last 5 minutes for one sensor (NOT chipID. API-ID can be found by clicking on your sensor on the Map).
V2

More detailed description

API sensor.commnunity

For the NodeMCU, the chipID is used as the ID. For other systems, X-Sensor is composed of a name for the system (e.g. raspi for Raspberry) and a unique ID (Raspberry: Serial in /proc/cpuinfo).

Example POST for SDS011:
header

Content-Type: application/json  
X-Pin: 1  
X-Sensor: esp8266-12345678

**Data

{
  "software_version": "your_version", 
  "sensordatavalues":[
    {"value_type":"P1","value":"66.04"},
    {"value_type":"P2","value":"53.32"}
  ]
}

Example POST for DHT22:
**Header

Content-Type: application/json  
X-Pin: 7  
X-Sensor: esp8266-12345678

**Data

{
   "software_version": "your_version", 
   "sensordatavalues":[
     {"value_type":"temperature","value":"22.30"},
     {"value_type":"humidity","value":"34.70"}
  ]
}

Other sensors:
BMP180: value_types: temperature, pressure; X-Pin: 3
BME280: value_types: temperature, humidity, pressure; X-Pin: 11
PMS1003 - PMS 7003: value_types: P1 (PM10), P2 (PM2.5); X-Pin: 1

The address of the API endpoint for delivering the data is https://api.sensor.community/v1/push-sensor-data/ (or https://api-rrd.madavi.de/data.php for Madavi.de).

3rd party APIs

OpenSenseMap

Opensensemap is a free platform for open sensor data. The website and API are open source. In addition to numerous projects that supply data to this platform, the fine dust sensor can also transfer its data to this platform. Users can display their values there and have them processed as a graph. A "box" created there has its own ID, which must be entered on the configuration page of the fine dust sensor. Then the API point must be activated in the configuration. Detailed description of the API: https://api.opensensemap.org/

aircms.online

Russian private air monitoring project. Consist of data receiving server and closed source map for displaying collected data. Data license is not currently specified. Archive data is not currently available. The data can be collected using API:

https://github.com/zakarlyukin/aircms/blob/master/docs/index.rst#push-sensors-data-to-storage

Send to own API

The data can be saved on a web server with this function. The "Send to own API" menu item on the configuration page of the fine dust sensor must be activated accordingly and the target address with server, path, port and optionally user and password must be entered. A simple PHP script is available for saving and later evaluating the data:

https://github.com/opendata-stuttgart/madavi-api/blob/master/data_simple.php

This saves the supplied data in a daily .csv file. The data is delivered in .json format and not in $_post format! This script can also be used as a basis for storing the data in your own database (program it yourself).

Issue #69 gives more hints and code examples for PHP:
https://github.com/opendata-stuttgart/meta/issues/69#issuecomment-314222830

Another example: a Python script as systemd service receives the data and sends it to Domoticz:
https://github.com/joba-1/airrohr2domoticz

Note: If HTTPS encryption is to be used, this must be done over port 443. The SSL certificate used on the server may be max. 2048 bits in size, because the memory of the NodeMCU can not handle more. Only the following SSL/TLS ciphers are supported (among other things for performance reasons): TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA\

InfluxDB

InfluxDB is a special database for time-based measurements or events. If an own InfluxDB server is available, the sensor data can also be sent directly to it. The default settings must be adapted accordingly for your own application. (Server, port, path, user) Only the address must be entered for the server, without additions such as HTTP or HTTPS, whereby the latter is not supported anyway.
Further information about InfluxDB
https://www.influxdata.com/
(For HTTPS, the same restrictions apply as for "Send to own API.")

Add a custom footer

Seiten

Dokumentation

Protokolle

for more, see Protokolle

Clone this wiki locally