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
Then, just add this other code to include the widget:<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>
<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
lang
option. For instance, to include the widget in Chinese (as shown on the right), use the following code: 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_aqiFeed({ container:"city-aqi-container", city:"beijing", lang:"cn" });
null
, English is used. C. Specifiying the display format
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).
Display Configuration | Result |
---|
D. Programatic callback
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:
will produce the following content:<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>
The
aqi
objects contains all the keywords mentionned in the section C (display format). E. Including multiple widgets
The result is: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>")); }
F. Feed usage
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.