diff --git a/source/_integrations/airvisual.markdown b/source/_integrations/airvisual.markdown
index 74c6595e11f0..468171fac96d 100644
--- a/source/_integrations/airvisual.markdown
+++ b/source/_integrations/airvisual.markdown
@@ -10,7 +10,7 @@ ha_codeowners:
- '@bachya'
---
-The `airvisual` sensor platform queries the [AirVisual](https://airvisual.com/) API for air quality data. Data can be collected via latitude/longitude or by city/state/country. The resulting information creates sensors for the Air Quality Index (AQI), the human-friendly air quality level, and the main pollutant of that area. Sensors that conform to either/both the [U.S. and Chinese air quality standards](https://www.clm.com/publication.cfm?ID=366) can be created.
+The `airvisual` sensor platform queries the [AirVisual](https://airvisual.com/) API for air quality data. Data can be collected via latitude/longitude or by city/state/country. The resulting information creates sensors for the Air Quality Index (AQI), the human-friendly air quality level, and the main pollutant of that area. Sensors that conform to either/both the [U.S. and Chinese air quality standards](https://www.clm.com/publication.cfm?ID=366) are created.
This platform requires an AirVisual API key, which can be obtained [here](https://airvisual.com/api). Note that the platform was designed using the "Community" package; the "Startup" and "Enterprise" package keys should continue to function, but actual results may vary (or not work at all).
@@ -18,7 +18,7 @@ The Community API key is valid for 12 months after which it will expire. You mus
-The "Community" API key is limited to 10,000 calls per month. In order to leave a buffer, the `airvisual` platform queries the API every 10 minutes (600 seconds) by default. Modification of this (via the `scan_interval` key) to a too-low value may result in your API key being deactivated.
+The "Community" API key is limited to 10,000 calls per month. In order to leave a buffer, the `airvisual` platform queries the API every 10 minutes (600 seconds) by default. Note that each item in the `geographies` list will consume an API call with each update.
@@ -27,8 +27,7 @@ The "Community" API key is limited to 10,000 calls per month. In order to leave
To enable the platform and gather data via latitude/longitude, add the following lines to your `configuration.yaml` file:
```yaml
-sensor:
- - platform: airvisual
+airvisual:
api_key: YOUR_AIRVISUAL_API_KEY
```
@@ -37,74 +36,74 @@ api_key:
description: Your AirVisual API key.
required: true
type: string
-monitored_conditions:
- description: "The air quality standard(s) to use (`us` for U.S., `cn` for Chinese)."
- required: true
- type: list
- default: ['us', 'cn']
-show_on_map:
- description: "Whether to show a marker on the map at the specified location."
- required: false
- type: boolean
- default: true
-scan_interval:
- description: "The rate in seconds at which AirVisual should be polled for new data."
- required: false
- type: integer
- default: 600
-latitude:
- description: The latitude of the location to monitor.
- required: false
- type: string
- default: "The latitude defined under the `homeassistant` key in `configuration.yaml`."
-longitude:
- description: The longitude of the location to monitor.
- required: false
- type: string
- default: "The longitude defined under the `homeassistant` key in `configuration.yaml`."
-city:
- description: The city to monitor.
- required: false
- type: string
-state:
- description: The state the city belongs to.
+geographies:
+ description: A list of geographical locations to monitor
required: false
- type: string
-country:
- description: The country the state belongs to.
- required: false
- type: string
+ type: [list, map]
+ keys:
+ latitude:
+ description: The latitude of the location to monitor.
+ required: inclusive
+ type: float
+ longitude:
+ description: The longitude of the location to monitor.
+ required: inclusive
+ type: float
+ city:
+ description: The city to monitor.
+ required: inclusive
+ type: string
+ state:
+ description: The state the city belongs to.
+ required: inclusive
+ type: string
+ country:
+ description: The country the state belongs to.
+ required: inclusive
+ type: string
{% endconfiguration %}
## Example Configurations
-Configuration using custom Latitude and Longitude:
+No explicit configuration (uses the `latitude` and `longitude` defined within `configuration.yaml`):
```yaml
-sensor:
- - platform: airvisual
+airvisual:
api_key: YOUR_AIRVISUAL_API_KEY
- monitored_conditions:
- - cn
- show_on_map: false
- scan_interval: 300
- latitude: 42.81212
- longitude: 108.12422
```
-Configuration using city, state, and country:
+Configuration using a single custom latitude and longitude:
```yaml
-sensor:
- - platform: airvisual
+airvisual:
api_key: YOUR_AIRVISUAL_API_KEY
- monitored_conditions:
- - us
- show_on_map: false
+ geographies:
+ latitude: 42.81212
+ longitude: 108.12422
scan_interval: 300
- city: Los Angeles
- state: California
- country: USA
+```
+
+Configuration using multiple custom latitude and longitude pairs:
+
+```yaml
+airvisual:
+ api_key: YOUR_AIRVISUAL_API_KEY
+ geographies:
+ - latitude: 42.81212
+ longitude: 108.12422
+ - latitude: 32.87336
+ longitude: -117.22743
+```
+
+Configuration using a single city, state, and country:
+
+```yaml
+airvisual:
+ api_key: YOUR_AIRVISUAL_API_KEY
+ geographies:
+ city: Los Angeles
+ state: California
+ country: USA
```
## Determining the City/State/Country
@@ -114,20 +113,17 @@ To easily determine the proper values for a particular location, use the [AirVis
For example, Sao Paulo, Brazil shows a breadcrumb title of `Brazil > Sao Paulo > Sao Paulo`. Thus, the proper configuration would look like this:
```yaml
-sensor:
- - platform: airvisual
- api_key: abc123
- monitored_conditions:
- - us
- - cn
- city: sao-paulo
- state: sao-paulo
- country: brazil
+airvisual:
+ api_key: YOUR_AIRVISUAL_API_KEY
+ geographies:
+ city: sao-paulo
+ state: sao-paulo
+ country: brazil
```
## Sensor Types
-When configured, the platform will create three sensors for each configured air quality standard:
+When configured, the platform will create three sensors for each air quality standard:
### Air Quality Index