From c8cdb9cb7062955be0645e10ace602fa41668084 Mon Sep 17 00:00:00 2001
From: Aaron Bach <bachya1208@gmail.com>
Date: Sat, 16 Sep 2017 02:33:58 -0600
Subject: [PATCH] Documentation updates for AirVisual (#3370)

---
 source/_components/sensor.airvisual.markdown | 67 +++++++++++++++++---
 1 file changed, 58 insertions(+), 9 deletions(-)

diff --git a/source/_components/sensor.airvisual.markdown b/source/_components/sensor.airvisual.markdown
index 98686274dcd..69c69336d67 100644
--- a/source/_components/sensor.airvisual.markdown
+++ b/source/_components/sensor.airvisual.markdown
@@ -14,10 +14,11 @@ ha_iot_class: "Cloud Polling"
 ---
 
 The `airvisual` sensor platform queries the [AirVisual](https://airvisual.com/) API for air quality
-data on the nearest city to a latitude and longitude. 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](http://www.clm.com/publication.cfm?ID=366) can be created.
+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](http://www.clm.com/publication.cfm?ID=366) can be
+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"
@@ -29,10 +30,10 @@ 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.
 </p>
 
-## {% linkable_title Configuring the Platform %}
+## {% linkable_title Configuring the Platform via Latitude/Longitude %}
 
-To enable this platform, add the following lines to your `configuration.yaml`
-file:
+To enable the platform and gather data via latitude/longitude, add the
+following lines to your `configuration.yaml` file:
 
 ```yaml
 sensor:
@@ -52,12 +53,60 @@ Configuration variables:
 - **monitored_conditions** (*Required*): the air quality standard(s) to use
 (`us` for U.S., `cn` for Chinese)
 - **latitude** (*Optional*): the latitude to monitor; if excluded, the latitude
-defined in `configuration.yaml` will be used
+defined under the `homeassistant` key in `configuration.yaml` will be used
 - **longitude** (*Optional*): the longitude to monitor; if excluded, the longitude
-defined in `configuration.yaml` will be used
+defined under the `homeassistant` key in `configuration.yaml` will be used
 - **radius** (*Optional*): the radius (in meters) around the latitude/longitude to
 search for the nearest city; defaults to `1000`
 
+## {% linkable_title Configuring the Platform via City/State/Country %}
+
+To enable the platform and gather data via city/state/country, add the
+following lines to your `configuration.yaml` file:
+
+```yaml
+sensor:
+  - platform: airvisual
+    api_key: abc123
+    monitored_conditions:
+      - us
+      - cn
+    city: southend-on-sea
+    state: essex
+    country: uk
+```
+
+Configuration variables:
+
+- **api_key** (*Required*): your AirVisual API key
+- **monitored_conditions** (*Required*): the air quality standard(s) to use
+(`us` for U.S., `cn` for Chinese)
+- **city** (*Optional*): the city to monitor
+- **state** (*Optional*): the state/region to monitor
+- **country** (*Optional*): the country to monitor
+
+To easily determine the proper values for a particular location, use the
+[AirVisual region directory](https://airvisual.com/world). Once you browse to the particular city you want,
+take note of the breadcrumb title, which is of the form
+`country > state/region > city`. Use this information to fill out
+`configuration.yaml`.
+
+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
+```
+
 ## {% linkable_title Sensor Types %}
 
 When configured, the platform will create three sensors for each configured