home
Here
map
mask
faq
search
contact
links

Publishing API for Dylos and Shinyei sensors

Note. The content on this page is outdated.
For the most recent upload API document, go to https://aqicn.org/data-feed/upload-api/

If you have a Dylos or Shinyei sensor, and you would like to publish its data on the World Air Quality Index, then this page is for you. One of the easiest solution for uploading the Dylos data is to use the ready made scripts available on github. But if you need to brew your own system, or upload data from the Shinyei sensor, then you can use the APIs described on this page.

Note that this API specification is not final, but still on-going work, so if you meet any difficulty with the integration, just contact us to get the support.


--

API Endpoint

http://sensor.aqicn.org/

API Method: Uploading data

post /sensor/upload
Parameters
  • id: Sensor ID, eg dylos.test-sensor-id
  • key: Sensor password - optional, only if the sensor ID is 'locked'.
  • time: Sensor time, with timezone information, in ISO 8601 format- eg 2014/10/08 18:03:45 +0800
  • location: Sensor position (latitude, longitude) - optional only if correlation with BAM sensor is requested

  • data: Array, containing all the raw readings
    • type: Sensor data type. For now, can be "dylos-0.5", "dylos-2.5", "shinyei-pdp42ns-2.5u" or "shinyei-pdp42ns-1u".
    • unit: Sensor data unit. For now, can be "pc" (particule count) or "lpo" (low pulse occupancy).
    • value: Sensor data reading. eg 94948 or 0.374

    Notes
    1. The above parameters are encapsulated within the argument 'postdata' of the post request.
    2. The LPO value must be between 0 and 1. 0 Means transparent, 1 Opaque. For more information on how to extrac the LPO from the Shinyei sensor, please refer to this page: api/shinyei.
Example: 
...
Return value:
  • result: Can be either ok or error.

    In case of ok result, the returned value will contain the sensor id as well as the upload data ids (for information purpose only). 
    ...

    In case of error, the returned value will contain a description (field msg) and an error code (field ecode) which can be one of the following:

    • 101: There are missing arugments from the posted data. Minimum arguments are id, time and data.
    • 102: Key is not valid - the sensor is protected by password and the provided password is not correct.
    • 103: No data posted (i.e empty array or data is not an array).
    • 104: Unit, type of value information not available from the data field.
    • 105: Sensor type is unknown.
    • 106: The field value is not numeric.
    • 107: Time string can not be decode (is it ISO 8601 complaiant?)
    • 108: SQL query failed. 
    ...

Example

 $ curl -i "http://sensor.aqicn.org/sensor/upload/" -d 'postdata={id:"dylos.test-sensor-id",time:"2014-10-16T19:20:31+08:00",data:[{type:"dylos-2.5",value:88,unit:"pc"}]}'
 
 HTTP/1.1 200 OK
 Date: Sun, 09 Nov 2014 08:28:34 GMT
 Server: Apache/2.2.15 (CentOS)
 X-Powered-By: PHP/5.3.3
 Vary: Accept-Encoding
 Connection: close
 Transfer-Encoding: chunked
 Content-Type: text/json; charset=utf-8
 
 {"result":"ok","sensorID":"588","dataids":[2825275]}


API Method: Getting the raw sensor data

get /sensor/download
Parameters
  • id: Sensor ID, eg dylos.test-sensor-id
  • callback: Optional JsonP callback (eg "foo").
Example : 
 http://sensor.aqicn.org/sensor/download/?id=dylos.test-sensor-id&callback=foo

Return value: 
...

Example

 $ curl -i "http://sensor.aqicn.org/sensor/download/?id=dylos.test-sensor-id&callback=foo"
 
 HTTP/1.1 200 OK
 Date: Sun, 09 Nov 2014 08:42:12 GMT
 Server: Apache/2.2.15 (CentOS)
 X-Powered-By: PHP/5.3.3
 Vary: Accept-Encoding
 Connection: close
 Transfer-Encoding: chunked
 Content-Type: text/json; charset=utf-8
 
 {"id":"dylos.test-sensor-id","data":{"dylos-0.5":[{"time":"1413458432","value":"89"}],"dylos-2.5":[{"time":"1413458432","value":"89"},{"time":"1413458431","value":"88"}]}}


About the Air Quality and Pollution Measurement:

About the Air Quality Levels

AQI Air Pollution Level Health Implications Cautionary Statement (for PM2.5)
0 - 50 Good Air quality is considered satisfactory, and air pollution poses little or no risk None
51 -100 Moderate Air quality is acceptable; however, for some pollutants there may be a moderate health concern for a very small number of people who are unusually sensitive to air pollution. Active children and adults, and people with respiratory disease, such as asthma, should limit prolonged outdoor exertion.
101-150 Unhealthy for Sensitive Groups Members of sensitive groups may experience health effects. The general public is not likely to be affected. Active children and adults, and people with respiratory disease, such as asthma, should limit prolonged outdoor exertion.
151-200 Unhealthy Everyone may begin to experience health effects; members of sensitive groups may experience more serious health effects Active children and adults, and people with respiratory disease, such as asthma, should avoid prolonged outdoor exertion; everyone else, especially children, should limit prolonged outdoor exertion
201-300 Very Unhealthy Health warnings of emergency conditions. The entire population is more likely to be affected. Active children and adults, and people with respiratory disease, such as asthma, should avoid all outdoor exertion; everyone else, especially children, should limit outdoor exertion.
300+ Hazardous Health alert: everyone may experience more serious health effects Everyone should avoid all outdoor exertion

To know more about Air Quality and Pollution, check the wikipedia Air Quality topic or the airnow guide to Air Quality and Your Health.

For very useful health advices of Beijing Doctor Richard Saint Cyr MD, check www.myhealthbeijing.com blog.


Usage Notice: All the Air Quality data are unvalidated at the time of publication, and due to quality assurance these data may be amended, without notice, at any time. The World Air Quality Index project has exercised all reasonable skill and care in compiling the contents of this information and under no circumstances will the World Air Quality Index project team or its agents be liable in contract, tort or otherwise for any loss, injury or damage arising directly or indirectly from the supply of this data.



Settings


Language Settings:


Temperature unit:
Celcius