# Air Quality Binding This binding uses the [AQIcn.org service](https://aqicn.org) for providing air quality information for any location worldwide. The World Air Quality Index project is a social enterprise project started in 2007. Its mission is to promote Air Pollution awareness and provide a unified Air Quality information for the whole world. The project is proving a transparent Air Quality information for more than 70 countries, covering more than 9000 stations in 600 major cities, via those two websites: [aqicn.org](https://aqicn.org) and [waqi.info](https://waqi.info). To use this binding, you first need to [register and get your API token](https://aqicn.org/data-platform/token/). ## Supported Things There is exactly one supported thing type, which represents the air quality information for an observation location. It has the `aqi` id. Of course, you can add multiple Things, e.g. for measuring AQI for different locations. ## Discovery Local Air Quality can be autodiscovered based on system location. You will have complete default configuration with your apiKey. ## Binding Configuration The binding has no configuration options, all configuration is done at Thing level. ## Thing Configuration The thing has a few configuration parameters: | Parameter | Description | |-----------|-------------------------------------------------------------------------| | apikey | Data-platform token to access the AQIcn.org service. Mandatory. | | location | Geo coordinates to be considered by the service. | | stationId | Unique ID of the measuring station. | | refresh | Refresh interval in minutes. Optional, the default value is 60 minutes. | For the location parameter, the following syntax is allowed (comma separated latitude and longitude): ```java 37.8,-122.4 37.8255,-122.456 ``` If you always want to receive data from specific station and you know its unique ID, you can enter it instead of the coordinates. This `stationId` can be found by using the following link: https://api.waqi.info/search/?token=TOKEN&keyword=NAME, replacing TOKEN by your apikey and NAME by the station you are looking for. ## Channels The AirQuality information that is retrieved is available as these channels: | Channel ID | Item Type | Description | |-----------------|----------------------|----------------------------------------------| | aqiLevel | Number | Air Quality Index | | aqiColor | Color | Color associated to given AQI Index. | | aqiDescription | String | AQI Description | | locationName | String | Nearest measuring station location | | stationId | Number | Measuring station ID | | stationLocation | Location | Latitude/longitude of measuring station | | pm25 | Number | Fine particles pollution level (PM2.5) | | pm10 | Number | Coarse dust particles pollution level (PM10) | | o3 | Number | Ozone level (O3) | | no2 | Number | Nitrogen Dioxide level (NO2) | | co | Number | Carbon monoxide level (CO) | | so2 | Number | Sulfur dioxide level (SO2) | | observationTime | DateTime | Observation date and time | | temperature | Number:Temperature | Temperature in Celsius degrees | | pressure | Number:Pressure | Pressure level | | humidity | Number:Dimensionless | Humidity level | | dominentpol | String | Dominent Polutor | `AQI Description` item provides a human-readable output that can be interpreted e.g. by MAP transformation. *Note that channels like* `pm25`, `pm10`, `o3`, `no2`, `co`, `so2` *can sometimes return* `UNDEF` *value due to the fact that some stations don't provide measurements for them.* ## Full Example airquality.map: ```text -=- UNDEF=No data NULL=No data NO_DATA=No data GOOD=Good MODERATE=Moderate UNHEALTHY_FOR_SENSITIVE=Unhealthy for sensitive groups UNHEALTHY=Unhealthy VERY_UNHEALTHY=Very unhealthy HAZARDOUS=Hazardous ``` airquality.things: ```java airquality:aqi:home "AirQuality" @ "Krakow" [ apikey="XXXXXXXXXXXX", location="50.06465,19.94498", refresh=60 ] airquality:aqi:warsaw "AirQuality in Warsaw" [ apikey="XXXXXXXXXXXX", location="52.22,21.01", refresh=60 ] airquality:aqi:brisbane "AirQuality in Brisbane" [ apikey="XXXXXXXXXXXX", stationId=5115 ] ``` airquality.items: ```java Group AirQuality Number Aqi_Level "Air Quality Index" (AirQuality) { channel="airquality:aqi:home:aqiLevel" } String Aqi_Description "AQI Level [MAP(airquality.map):%s]" (AirQuality) { channel="airquality:aqi:home:aqiDescription" } Number Aqi_Pm25 "PM\u2082\u2085 Level" (AirQuality) { channel="airquality:aqi:home:pm25" } Number Aqi_Pm10 "PM\u2081\u2080 Level" (AirQuality) { channel="airquality:aqi:home:pm10" } Number Aqi_O3 "O\u2083 Level" (AirQuality) { channel="airquality:aqi:home:o3" } Number Aqi_No2 "NO\u2082 Level" (AirQuality) { channel="airquality:aqi:home:no2" } Number Aqi_Co "CO Level" (AirQuality) { channel="airquality:aqi:home:co" } Number Aqi_So2 "SO\u2082 Level" (AirQuality) { channel="airquality:aqi:home:so2" } String Aqi_LocationName "Measuring Location" (AirQuality) { channel="airquality:aqi:home:locationName" } Location Aqi_StationGeo "Station Location" (AirQuality) { channel="airquality:aqi:home:stationLocation" } Number Aqi_StationId "Station ID" (AirQuality) { channel="airquality:aqi:home:stationId" } DateTime Aqi_ObservationTime "Time of observation [%1$tH:%1$tM]" (AirQuality) { channel="airquality:aqi:home:observationTime" } Number:Temperature Aqi_Temperature "Temperature" (AirQuality) { channel="airquality:aqi:home:temperature" } Number:Pressure Aqi_Pressure "Pressure" (AirQuality) { channel="airquality:aqi:home:pressure" } Number:Dimensionless Aqi_Humidity "Humidity" (AirQuality) { channel="airquality:aqi:home:humidity" } ``` airquality.sitemap: ```perl sitemap airquality label="Air Quality" { Frame { Text item=Aqi_Level valuecolor=[ Aqi_Level=="-"="lightgray", Aqi_Level>=300="#7e0023", >=201="#660099", >=151="#cc0033", >=101="#ff9933", >=51="#ffde33", >=0="#009966" ] Text item=Aqi_Description valuecolor=[ Aqi_Description=="HAZARDOUS"="#7e0023", =="VERY_UNHEALTHY"="#660099", =="UNHEALTHY"="#cc0033", =="UNHEALTHY_FOR_SENSITIVE"="#ff9933", =="MODERATE"="#ffde33", =="GOOD"="#009966" ] } Frame { Text item=Aqi_Pm25 Text item=Aqi_Pm10 Text item=Aqi_O3 Text item=Aqi_No2 Text item=Aqi_Co Text item=Aqi_So2 } Frame { Text item=Aqi_LocationName Text item=Aqi_ObservationTime Text item=Aqi_Temperature Text item=Aqi_Pressure Text item=Aqi_Humidity } Frame label="Station Location" { Mapview item=Aqi_StationGeo height=10 } } ``` airquality.rules: ```java rule "Change lamp color to reflect Air Quality" when Item Aqi_Description changed then var String hsb switch Aqi_Description.state { case "HAZARDOUS": hsb = "343,100,49" case "VERY_UNHEALTHY": hsb = "280,100,60" case "UNHEALTHY": hsb = "345,100,80" case "UNHEALTHY_FOR_SENSITIVE": hsb = "30,80,100" case "MODERATE": hsb = "50,80,100" case "GOOD": hsb = "160,100,60" } Lamp_Color.sendCommand(hsb) end ```