pm_25 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 00dac5016f468d768d295752677967f3073c757e
+  data.tar.gz: c592db0adc0ac25c6e4732a5849fd3319014b06a
+SHA512:
+  metadata.gz: debccc45f01e29b5b3104fed7452429c1c556dc674bf3015896657331f33da8e5821bf1304e254c2ee07ec8e85ba3b0069dd188a1b27a602b7cab165b4a1c413
+  data.tar.gz: 4e9f749a2b868045f9dc9c0bbd93f88eecc258677bf43f605a3b781f62171287395a182fdbbff4e049b3202cdf6bd2104d6cc9e8fa4705e552ca8a1a26849a38

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.idea/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pm25.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jakukyo Friel
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,114 @@
+# Pm25
+
+A Ruby wrapper for pm25.in API and other PM 2.5 related utility functions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pm_25'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pm_25
+
+## Usage
+
+```ruby
+require 'pm_25'
+PM25.Func(args)
+```
+
+The following APIs of pm25.in 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 [pm25.in official api
+documentation][api_doc].
+
+[api_doc]: http://www.pm25.in/api_doc
+
+I only implemented APIs I care, and I guess in most cases these is 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.)
+
+pm25.in requires a token to access its api.
+You can apply one at [here][api_doc].
+
+`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 [pm25.in official api documentation][api_doc].
+
+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 bing.com, thus does not need a token.
+For example:
+
+```ruby
+PM25.bing_pm25 '北京'
+```
+
+pm25.in uses CN standard for AQI category.
+If you want to use US standard instead, use `pm25_level`.
+For example:
+
+```ruby
+PM25.pm25_level(123)
+```
+
+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:
+
+http://www.rubydoc.info/gems/pm25/
+
+### Command line usage
+
+We also provide a command line utility to query PM 2.5 info for the
+specified city:
+
+```sh
+; 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
+exertion.
+```
+
+If you does not provide a city argument, it will use environment variable `PM25_IN_CITY`.
+
+If something goes wrong with pm25.in, (say, you does not provide a token), it
+ will use bing.com instead.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/pm25/fork )
+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

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/bin/pm25

@@ -0,0 +1,13 @@
+require 'pm25'
+
+if ARGV.empty?
+  city = ENV['PM25_IN_CITY']
+else
+  city = ARGV[0]
+end
+
+pm25_info = PM25.pm25_level(PM25.just_pm25(city, ENV['PM25_IN_TOKEN']))
+
+puts "#{city}: #{pm25_info[:pm25]}, #{pm25_info[:category]}"
+puts pm25_info[:meaning]
+puts pm25_info[:action]

data/lib/pm_25/version.rb

@@ -0,0 +1,3 @@
+module PM25
+  VERSION = "0.0.1"
+end

data/lib/pm_25.rb

@@ -0,0 +1,243 @@
+require 'pm_25/version'
+
+require 'nokogiri'
+require 'json'
+require 'open-uri'
+require 'rest_client'
+require 'time-lord'
+
+module PM25
+  # Yes, pm25.in requires a token but uses http!
+  API_base = 'http://www.pm25.in/api/querys/'
+
+  module_function
+
+  # Use environment variable or the value
+  # from config at the current directory.
+  # If all failed, use the default value.
+  #
+  # @param [String] constant_name
+  # @param [String] default_value
+  # @return [String]
+  def get_config(constant_name, default_value=nil)
+    if ENV[constant_name]
+      ENV[constant_name]
+    elsif File.exist?('config.json')
+      open('config.json') do |f|
+        JSON.parse(f.read)[constant_name]
+      end
+    else
+      default_value
+    end
+  end
+
+  # Use environment variable PM25_IN_TOKEN
+  # or the value from config at the current directory.
+  # If all failed, use the test token.
+  # You can apply a token at pm25.in:
+  # http://www.pm25.in/api_doc
+  #
+  # @return [String] token
+  def get_token
+    test_token= '5j1znBVAsnSf5xQyNQyq'
+    get_config('PM25_IN_TOKEN', test_token)
+  end
+
+  # Use environment variable PM25_IN_CITY
+  # or the value from config at the current directory.
+  #
+  # @return [String] city
+  def get_default_city
+    get_config('PM25_IN_CITY')
+  end
+
+  # @param [String] interface of api
+  # @param [Hash] params (additional) options
+  # @return [Hash] result
+  # @return [Fixnum] error code
+  # TODO pm25.in tends to 502, need to email complaints and handle this.
+  def access_api(interface, params={})
+    params[:token] ||= get_token
+    res = RestClient.get(API_base + interface, {params: params})
+    if res.code == 200
+      JSON.parse res.body
+    else
+      res.code
+    end
+  end
+
+
+  # Get PM 2.5 info of all stations in the specified city.
+  # API frequency limit: 500 per hour.
+  #
+  # @param [String] city You can use
+  # - Chinese (e.g. 广州)
+  # - area code (e.g. 020)
+  # - Pinyin (e.g. guangzhou)
+  # If there is ambiguity in Pinyin, use `shi` as postfix, for example:
+  # 泰州 is taizhoushi, and 台州 is taizhou.
+  # For more information, see http://www.pm25.in/
+  # @return [Array<Hash>] an array of all stations
+  # Every station includes:
+  # * aqi (according to CN standard)
+  # * area
+  # * pm2_5
+  # * pm2_5_24h (moving average)
+  # * position_name (station name)
+  # * primary_pollutant
+  # * quality (优、良、轻度污染、中度污染、重度污染、严重污染 according to CN standard)
+  # * station_code
+  # * time_point (publish time of air condition)
+  #
+  # Example:
+  #
+  #   pm25('zhuhai')
+  #
+  # [
+  #     {
+  #         "aqi"=> 82,
+  #         "area"=> "珠海",
+  #         "pm2_5"=> 31,
+  #         "pm2_5_24h"=> 60,
+  #         "position_name"=> "吉大",
+  #         "primary_pollutant"=> "颗粒物(PM2.5)",
+  #         "quality"=> "良",
+  #         "station_code"=> "1367A",
+  #         "time_point"=> "2013-03-07T19:00:00Z"
+  #     },
+  #     ...
+  #     ...
+  #     ...
+  #     {
+  #         "aqi"=> 108,
+  #         "area"=> "珠海",
+  #         "pm2_5"=> 0,
+  #         "pm2_5_24h"=> 53,
+  #         "position_name"=> "斗门",
+  #         "primary_pollutant"=> "臭氧8小时",
+  #         "quality"=> "轻度污染",
+  #         "station_code"=> "1370A",
+  #         "time_point"=> "2013-03-07T19:00:00Z"
+  #     },
+  #     {
+  #         "aqi"=> 99,
+  #         "area"=> "珠海",
+  #         "pm2_5"=> 39,
+  #         "pm2_5_24h"=> 67,
+  #         "position_name"=> null,
+  #         "primary_pollutant"=> null,
+  #         "quality"=> "良",
+  #         "station_code"=> null,
+  #         "time_point"=> "2013-03-07T19:00:00Z"
+  #     }
+  # ]
+  def pm25(city=get_default_city, token=nil)
+    access_api('pm2_5.json', city: city, token: token)
+  end
+
+  # Get a list of cites providing PM 2.5 data.
+  # API frequency limit: 10 per hour.
+  # @param [String] token
+  # @return [Array] city list
+  # @return [Fixnum] error code
+  def available_cities(token=get_token)
+    res = RestClient.get 'http://www.pm25.in/api/querys.json', {params: {token: token}}
+    if res.code == 200
+      JSON.parse(res.body)['cities']
+    else
+      res.code
+    end
+  end
+
+  # Get PM 2.5 data for all cities.
+  # API frequency limit: 5 per hour.
+  # @param [String] token
+  # @return [Hash]
+  # @return [Fixnum] error code
+  def all_cities(token=nil)
+    access_api('all_cities.json', token: token)
+  end
+
+  # Get average data for all cities. (Cities are sorted by AQI.)
+  # API frequency limit: 15 per hour.
+  # @param [String] token
+  # @return [Hash]
+  # @return [Fixnum] error code
+  def aqi_ranking(token=nil)
+    access_api('aqi_ranking.json', token: token)
+  end
+
+
+  # Get PM 2.5 from bing.com
+  # @param [String] city only accept Chinese
+  # @return [Fixnum] PM 25 value
+  def bing_pm25(city)
+    city = URI.encode(city)
+    bing_url = "http://cn.bing.com/search?q=#{city}+pm2.5"
+    html = Nokogiri.parse(open(bing_url).read)
+    html.at('#msn_pm25rt .b_xlText').content.to_i
+  end
+
+  # Get PM 2.5 value for city.
+  # Fallback to bing.com.
+  # Return PM 2.5 value only.
+  # @param [String] city only accept Chinese
+  # @param [String] token
+  # @return [Fixnum] average PM 2.5 value for stations
+  def just_pm25(city=get_default_city, token=nil)
+    result = pm25(city, token)
+    # error on pm25.in api
+    if result.is_a? Fixnum
+      bing_pm25(city)
+    elsif result.include? 'error'
+      bing_pm25(city)
+    else
+      publish_time = Time.parse(result[-1]['time_point'])
+      # Data on pm25.in is too old.
+      # According to GB 3095-2013, PM 2.5 should have hourly
+      # average values for at least 20 hours a day.
+      # http://hbj.shanghang.gov.cn/hjjc/gldt/201411/P020141110361645902554.pdf
+      if Time.now - publish_time > 2.hours
+        bing_pm25(city)
+      else
+        result[-1]['pm2_5']
+      end
+    end
+  end
+
+
+  # Get AQI category, meaning and action according to US standard.
+  # @param [Fixnum]
+  # @return [Hash{Symbol: Fixnum, Symbol: String, Symbol: String, Symbol: String}]
+  def pm25_level(pm25)
+    if pm25 <= 12
+      aqi_category = 'Good'
+      aqi_meaning = 'Air quality is considered satisfactory, and air pollution poses little or no risk.'
+      aqi_action = 'None'
+    elsif pm25 <= 35.4
+      aqi_category = 'Moderate'
+      aqi_meaning = 'Air quality is acceptable; however, for some pollutants there may be a moderate health concern for a very small number of people who are unusually sensitive to air pollution.'
+      aqi_action = 'Unusually sensitive people should consider reducing prolonged or heavy exertion.'
+    elsif pm25 <= 55.4
+    aqi_category = 'Unhealthy for sensitive Groups'
+    aqi_meaning = 'Members of sensitive groups may experience health effects. The general public is not likely to be affected.'
+    aqi_action = 'People with heart or lung disease, children and older adults should reduc e prolonged or heavy exertion'
+    elsif pm25 <= 150.4
+      aqi_category = 'Unhealthy'
+      aqi_meaning = 'Everyone may begin to experience health effects; members of sensitive groups may experience more serious health effects.'
+      aqi_action = 'People with heart or lung disease, children and older adults should avoid prolonged or heavy exertion. Everyone else should reduce prolonged or heavy exertion.'
+    elsif pm25 <= 250.4
+      aqi_category = 'Very Unhealthy'
+      aqi_meaning = 'Health warnings of emergency conditions. The entire population is more likely to be affected.'
+      aqi_action = 'People with heart or lung disease, children and older adults should avoid all physical activity outdoors. Everyone else should avoid prolonged or heavy exertion.'
+    else
+      aqi_category = 'Hazardous'
+      aqi_meaning = 'Health alert: everyone may experience more serious health effects'
+      aqi_action = 'Avoid all physical activity outdoors.'
+    end
+  {pm25: pm25,
+   category: aqi_category,
+   meaning: aqi_meaning,
+   action: aqi_action}
+  end
+end

data/pm_25.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pm_25/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'pm_25'
+  spec.version       = PM25::VERSION
+  spec.authors       = ['Jakukyo Friel']
+  spec.email         = ['weakish@gmail.com']
+  spec.summary       = %q{Fetch PM 2.5 data in China.}
+  spec.description   = %q{A Ruby wrapper for pm25.in API and other PM 2.5
+related utility functions.}
+  spec.homepage      = 'https://github.com/weakish/pm_25'
+  spec.license       = 'MIT'
+  spec.metadata      = {
+      'repository' => 'https://github.com/weakish/pm_25.git',
+      'documentation' => 'http://www.rubydoc.info/gems/pm_25/',
+      'issues' => 'https://github.com/weakish/pm_25/issues',
+      'wiki' => 'https://github.com/weakish/pm_25/wiki'
+  }
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'nokogiri', '~> 1.6'
+  spec.add_runtime_dependency 'rest_client', '~> 1.8'
+  spec.add_runtime_dependency 'time-lord', '~> 1.0'
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: pm_25
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Jakukyo Friel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rest_client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: time-lord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: |-
+  A Ruby wrapper for pm25.in API and other PM 2.5
+  related utility functions.
+email:
+- weakish@gmail.com
+executables:
+- pm25
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/pm25
+- lib/pm_25.rb
+- lib/pm_25/version.rb
+- pm_25.gemspec
+homepage: https://github.com/weakish/pm_25
+licenses:
+- MIT
+metadata:
+  repository: https://github.com/weakish/pm_25.git
+  documentation: http://www.rubydoc.info/gems/pm_25/
+  issues: https://github.com/weakish/pm_25/issues
+  wiki: https://github.com/weakish/pm_25/wiki
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Fetch PM 2.5 data in China.
+test_files: []
+has_rdoc: