Air Quality Widget - New Improved Feed

Posted on July 28th 2015
Share: aqicn.org/faq/2015-07-28/air-quality-widget-new-improved-feed

{ widget : feed }

In order to improve the integration of our AQI widgets within external websites, we have developped a new widget API feed. Compared to the existing widget feed, this new API feed provides much more flexibility for the integration, but also many more options for customzing the widget appearance.

You can, for instance, display a tiny widget as simple as ... (move your mouse over the AQI number in order view the details), or a larger widget with details about the past 24 hours pollutants as shown on the right.

The new framework also supports templating, mutiple languages (English, Simplified and traditional Chinese, Spanish, ...) as well as possibility to do programatic integration with data based javascript callbacks.

A. Basic setup

The basic integration is simple and straight forward. You first need to add the following piece of code:
  
<script  type="text/javascript"  charset="utf-8">  
    (function(w,d,t,f){  w[f]=w[f]||function(c,k,n){s=w[f],k=s['k']=(s['k']||(k?('&k='+k):''));s['c']=  
    c=(c  instanceof  Array)?c:[c];s['n']=n=n||0;L=d.createElement(t),e=d.getElementsByTagName(t)[0];  
    L.async=1;L.src='//feed.aqicn.org/feed/'+(c[n].city)+'/'+(c[n].lang||'')+'/feed.v1.js?n='+n+k;  
    e.parentNode.insertBefore(L,e);  };  })(  window,document,'script','_aqiFeed'  );    
</script>
Then, just add this other code to include the widget:
  
<span  id="city-aqi-container"></span>  
  
<script  type="text/javascript"  charset="utf-8">  
    _aqiFeed({  container:"city-aqi-container",  city:"beijing"  });  
</script>

The function _aqiFeed takes as argument the configuration block for the widget. The parameter container: "city-aqi-container" refers to the id of the tag in which you want to insert the widget (eg <span id='city-aqi-container'></span>), and the parameter city the name of the city for which you want to show the current Air Quality reading (eg city: "london").

B. Specifiying the Language

...
You can also specify the language to be used by setting the lang option. For instance, to include the widget in Chinese (as shown on the right), use the following code:
  
_aqiFeed({  
  container:"city-aqi-container",  
  city:"beijing",  
  lang:"cn"  
});  
The currently supported languages are Chinese simplifed "cn", Chinese traditonal "hk", Japanese "jp", Korean "kr", Russia "ru", Spanish "es", French "fr" and Polish "pl". If not specified or set to null, English is used.

C. Specifiying the display format

...
It is possible to customize the text to be displayed within the widget by specifiying the display option. For instance, to display with both the textual "AQI" name as well as the update time (as shown on the widget on the left), you can use the following code:
  
_aqiFeed({    
  display:"%cityname  AQI  is  %aqi<br><small>on  %date</small>",  
  container:"city-aqi-container-display",    
  city:"beijing"  
});  

The parameter display is an HTML-based string, and can contain any of the the following keywords:
  • %cityname for the name of the city (eg Beijing),
  • %aqi for the decorated AQI value (eg 58),
  • %aqiv for the undecorated (raw text) AQI value (eg 58),
  • %style for the css declaration of the decorated AQI details (eg background-color: #ffde33;color:#000000;),
  • %time for the time at which the AQI was updated (eg Wed 20:00),
  • %impact for the associated health impact (eg Good, Moderate...)
  • %attribution for the AQI data attribution ( eg Beijing Environmental Protection Monitoring Center)
  • %details for the full AQI details (the content of the popup displayed when moving the mouse over the AQI value).
Few examples:
Display ConfigurationResult

D. Programatic callback

If you prefer DIY integration, can you can also specify a javascript function callback to be when the data is loaded.
Just add the option callback in the parameter block, such as for instance:
  
_aqiFeed({  city:"beijing",  callback:function(aqi){  
  /*  Do  whatever  you  want  with  the  AQI  object  */  
  console.log(aqi);    
}  });

For instance, assuming that you are also using jquery, the following code:
  
<div  id='my-container'></div>  
<script  type="text/javascript"  charset="utf-8">  
_aqiFeed({  city:"beijing",  lang:"pl",  callback:function(aqi){  
  $("#my-container").html(aqi.details);  
}  });  
</script>
will produce the following content:


The aqi objects contains all the keywords mentionned in the section C (display format).

E. Including multiple widgets

Including multiple widgets in a single page is possible. All you need is to pass to the _aqiFeed function an array with all the widgets you need to include. For instance, to insert London, Paris and New York, can do use this code:
  
var  cities  =  ["london",  "newyork",  "seoul",  "guangzhou",  "tokyo",  "shanghai",  "paris","hongkong"];  
  
var  aqiWidgetConfig  =  [];    
cities.forEach(function(city)  {  aqiWidgetConfig.push({city:city,  callback:  displayCity});  });  
_aqiFeed(aqiWidgetConfig);  
  
function  displayCity(aqi)  {  
  $("#mutiple-city-aqi").append(aqi.text("<center>%cityname<br>%aqi<br><small>%date</small></center>"));  
}  
The result is:

F. Feed usage

This widget feed is provided for free, and for the sole purpose of integrating the feed into other websites (i.e. apps are excluded), and under the condition of reasonable and acceptable use. We reserve the right to change the feed structure (data format) at any time and without prior notice, so better to contact us if you plan to do a custom integration.

When doing the integration, there are few deontological rules which should be applied when using the data feed:
  • First, always make sure that the attribution to the originating EPA is present. All the Air Quality data you can find on the World Air Quality Index project is thanks to the hard work from all the EPA's all over the world, so please make sure to provide the attribution for their work too. If you use the programtic API, the attribution is available from the attribution field.

  • If you are from an instution and usign the data, please, show respect and pay back the credits for our work. If you are trying to scrape the data feed, please, keep in mind that this project relies on sponsorship and cooperation projects, so consider supporting us rather than scrapping us, especially if you are a large scale institution or university.

  • As a matter of fact, do not act like the WRI (World Resource Institute ): Scrapping the overall World Air Quality Index project data feed, and beeing so cheap that they would not even give any attribution for our work, and this despite their 80 millions annual USD fundings. Don't believe us? Check this snapshot.

G. Future improvments

This is the first version of this new widget feed API. There are quite a few improvments already in the pipeline, such as adjustable graphic width and height, selectable AQI scale, etc. If you would like to suggest any other specifc improvment, feel free to send us a message.


Click here to see all the FAQ entries
  • Nitrogen Dioxyde (NO2) in our atmosphere
  • Ozone AQI Scale update
  • Kriging Interpolation




  • comments powered by Disqus

    關於空氣質量與空氣污染指數

    本網站採用的污染指數和顏色與EPA是完全相同的。 EPA的指數可以從 AirNow上查到

    空气质量指数空气质量指数级别(状况)及表示颜色对健康影响情况建议采取的措施
    0 - 50一级(优)空气质量令人满意,基本无空气污染各类人群可正常活动
    51 -100二级(良)空气质量可接受,但某些污染物可能对极少数异常敏感人群健康有较弱影响极少数异常敏感人群应减少户外活动
    101-150三级(轻度污染)易感人群症状有轻度加剧,健康人群出现刺激症状儿童、老年人及心脏病、呼吸系统疾病患者应减少长时间、高强度的户外锻炼
    151-200四级(中度污染)进一步加剧易感人群症状,可能对健康人群心脏、呼吸系统有影响儿童、老年人及心脏病、呼吸系统疾病患者避免长时间、高强度的户外锻炼,一般人群适量减少户外运动
    201-300五级(重度污染)心脏病和肺病患者症状显著加剧,运动耐受力降低,健康人群普遍出现症状儿童、老年人及心脏病、肺病患者应停留在室内,停止户外运动,一般人群减少户外运动
    300+六级(严重污染)健康人群运动耐受力降低,有明显强烈症状,提前出现某些疾病儿童、老年人和病人应停留在室内,避免体力消耗,一般人群避免户外活动
    (参考详见http://zh.wikipedia.org/wiki/空气质量指数)

    如果你想了解更多有關空氣質量與污染,詳見維基百科或者 AirNow

    有關健康建議詳​​見北京的Richard Saint Cyr MD醫生的博客:www.myhealthbeijing.com


    Usage Notice: All the Air Quality data are unvalidated at the time of publication, and due to quality assurance these data may be amended, without notice, at any time. The World Air Quality Index project has exercised all reasonable skill and care in compiling the contents of this information and under no circumstances will the World Air Quality Index project team or its agents be liable in contract, tort or otherwise for any loss, injury or damage arising directly or indirectly from the supply of this data.



    設定


    選擇語言:


    Temperature unit:
    Celcius