# 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 Bridge: The binding supports a bridge to connect to the [AQIcn.org service](https://aqicn.org). A bridge uses the thing ID "api". Station: Represents the air quality information for an observation location. Of course, you can add multiple Stations, e.g. for measuring AQI for different locations. ## Discovery Local Air Quality can be autodiscovered based on system location. You will created a Bridge with your apiKey. ## Bridge Configuration The bridge configuration only holds the api key : | Parameter | Description | |-----------|-------------------------------------------------------------------------| | apiKey | Data-platform token to access the AQIcn.org service. Mandatory. | ## Thing Configuration The 'Station' thing has a few configuration parameters: | Parameter | Description | |-----------|-------------------------------------------------------------------------| | 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. ### Thing properties Once created, at first execution, the station's properties will be filled with informations gathered from the web service : - Nearest measuring station location - Measuring station ID - Latitude/longitude of measuring station ## Channels The AirQuality information that is retrieved for a given is available as these channels: ### AQI Channels Group - Global Results | Channel ID | Item Type | Description | |-----------------|----------------------|----------------------------------------------| | alert-level | Number | Alert level (*) associated to AQI Index. | | index | Number | Air Quality Index | | timestamp | DateTime | Observation date and time | | dominent | String | Dominent Pollutant | | icon | Image | Pictogram associated to alert-level | | color | Color | Color associated to alert level. | ### Weather Channels Group | Channel ID | Item Type | Description | |-----------------|----------------------|----------------------------------------------| | temperature | Number:Temperature | Temperature in Celsius degrees | | pressure | Number:Pressure | Pressure level | | humidity | Number:Dimensionless | Humidity level | | dew-point | Number:Temperature | Dew point temperature | | wind-speed | Number:Speed | Wind speed | ### Pollutants Channels Group For each pollutant (PM25, PM10, O3, NO2, CO, SO2) , depending upon availability of the station, you will be provided with the following informations | Channel ID | Item Type | Description | |-----------------|----------------------|----------------------------------------------| | value | Number:Density | Measured density of the pollutant | | index | Number | AQI Index of the single pollutant | | alert-level | Number | Alert level associate to the index | (*) The alert level is described by a color : | Code | Color | Description | |------|--------|--------------------------------| | 0 | Green | Good | | 1 | Yellow | Moderate | | 2 | Orange | Unhealthy for Sensitive Groups | | 3 | Red | Unhealthy | | 4 | Purple | Very Unhealthy | | 5 | Maroon | Hazardous | ## Full Example airquality.things: ```java Bridge airquality:api:main "Bridge" [apiKey="xxxyyyzzz"] { station home "Krakow"[location="50.06465,19.94498", refresh=60] } ``` airquality.items: ```java Group AirQuality Number Aqi_Level "Air Quality Index" (AirQuality) { channel="airquality:station:main:home:aqi#index" } Number Aqi_Pm25 "PM\u2082\u2085 Level" (AirQuality) { channel="airquality:station:main:home:pm25#value" } Number Aqi_Pm10 "PM\u2081\u2080 Level" (AirQuality) { channel="airquality:station:main:home:pm10#value" } Number Aqi_O3 "O\u2083 Level" (AirQuality) { channel="airquality:station:main:home:o3#value" } Number Aqi_No2 "NO\u2082 Level" (AirQuality) { channel="airquality:station:main:home:no2#value" } Number Aqi_Co "CO Level" (AirQuality) { channel="airquality:station:main:home:co#value" } Number Aqi_So2 "SO\u2082 Level" (AirQuality) { channel="airquality:station:main:home:so2#value" } DateTime Aqi_ObservationTime "Time of observation [%1$tH:%1$tM]" (AirQuality) { channel="airquality:station:main:home:aqi#timestamp" } Number:Temperature Aqi_Temperature "Temperature" (AirQuality) { channel="airquality:station:main:home:weather#temperature" } Number:Pressure Aqi_Pressure "Pressure" (AirQuality) { channel="airquality:station:main:home:weather#pressure" } Number:Dimensionless Aqi_Humidity "Humidity" (AirQuality) { channel="airquality:station:main:home:weather#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_FSG"="#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_ObservationTime Text item=Aqi_Temperature Text item=Aqi_Pressure Text item=Aqi_Humidity } } ``` 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_FSG": hsb = "30,80,100" case "MODERATE": hsb = "50,80,100" case "GOOD": hsb = "160,100,60" } Lamp_Color.sendCommand(hsb) end ```