fetch PM 2.5 data in China via and

View project on GitHub


Gem Version

A Ruby wrapper for API and other PM 2.5 related utility functions.


Add this line to your application's Gemfile:

gem 'pm_25'

And then execute:

$ bundle

Or install it yourself as:

$ gem install pm_25


require 'pm_25'

The following APIs of are implemented:

  • 1.1 pm25 Get PM 2.5 info of all stations in the specified city.
  • 1.11 available_cities Get a list of cites providing PM 2.5 data.
  • 1.12 all_cities Get PM 2.5 data for all cities.
  • 1.13 aqi_ranking Get average data for all cities. (Cities are sorted by AQI.)

1.1, 1.11 etc are for reference of official api documentation.

I only implemented APIs I care, and I guess in most cases these are the APIs you actually want to use.

However, if you do need other APIs, feel free to send a pull request. You can use PM25.access_api. (Actually implementing other APIs is trivial with this.) requires a token to access its api. You can apply one at here.

pm25 will look for a token in the following order:

  • Token argument when invoking functions.
  • Environment virable PM25_IN_TOKEN
  • "PM25_IN_TOKEN": 'your_token' in config.json at the current directory.
  • The default test token at official api documentation.

Note that the test token is barely usable (too many people use it).

If you does not have a token, you can use bing_pm25 to get the average PM 2.5 value for the specified city. This function uses data from, thus does not need a token. For example:

PM25.bing_pm25 '北京' uses CN standard for AQI category. If you want to use US standard instead, use pm25_level. For example:


It will return a hash containing:

  • PM 2.5 value
  • AQI category
  • AQI category meaning
  • suggested action

For other functions and usage details, check API documentation:

Command line usage

We also provide a command line utility to query PM 2.5 info for the specified city:

; PM25_IN_TOKEN='your_token' pm25 北京
北京: 106, Unhealthy
Everyone may begin to experience health effects; members of sensitive groups may
experience more serious health effects.
People with heart or lung disease, children and older adults should avoid
prolonged or heavy exertion. Everyone else should reduce prolonged or heavy

If you does not provide a city argument, it will use environment variable PM25_IN_CITY.

If something goes wrong with, (say, you does not provide a token), it will use instead.


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request