Add docs for AirVisual config entry (#12166)

* Add docs for AirVisual config entry

* Update schema

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
 
 <div class='note warning'>
 
-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.
 
 </div>
 
@@ -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:
+airvisual:
-  - platform: airvisual
     api_key: YOUR_AIRVISUAL_API_KEY
 ```
 
@@ -37,74 +36,74 @@ api_key:
   description: Your AirVisual API key.
   required: true
   type: string
-monitored_conditions:
+geographies:
-  description: "The air quality standard(s) to use (`us` for U.S., `cn` for Chinese)."
+  description: A list of geographical locations to monitor
-  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
+  type: [list, map]
-  default: true
+  keys:
-scan_interval:
+    latitude:
-  description: "The rate in seconds at which AirVisual should be polled for new data."
+      description: The latitude of the location to monitor.
-  required: false
+      required: inclusive
-  type: integer
+      type: float
-  default: 600
+    longitude:
-latitude:
+      description: The longitude of the location to monitor.
-  description: The latitude of the location to monitor.
+      required: inclusive
-  required: false
+      type: float
-  type: string
+    city:
-  default: "The latitude defined under the `homeassistant` key in `configuration.yaml`."
+      description: The city to monitor.
-longitude:
+      required: inclusive
-  description: The longitude of the location to monitor.
+      type: string
-  required: false
+    state:
-  type: string
+      description: The state the city belongs to.
-  default: "The longitude defined under the `homeassistant` key in `configuration.yaml`."
+      required: inclusive
-city:
+      type: string
-  description: The city to monitor.
+    country:
-  required: false
+      description: The country the state belongs to.
-  type: string
+      required: inclusive
-state:
+      type: string
-  description: The state the city belongs to.
-  required: false
-  type: string
-country:
-  description: The country the state belongs to.
-  required: false
-  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:
+airvisual:
-  - platform: 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:
+airvisual:
-  - platform: airvisual
     api_key: YOUR_AIRVISUAL_API_KEY
-    monitored_conditions:
+    geographies:
-      - us
+        latitude: 42.81212
-    show_on_map: false
+        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:
+airvisual:
-  - platform: airvisual
+    api_key: YOUR_AIRVISUAL_API_KEY
-    api_key: abc123
+    geographies:
-    monitored_conditions:
+        city: sao-paulo
-      - us
+        state: sao-paulo
-      - cn
+        country: brazil
-    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