MISC - prototype

Author: Xuhao

.gitignore

@@ -1,16 +1,17 @@
+*.gem
 *.rbc
-*.sassc
-.sass-cache
-capybara-*.html
-.rspec
-/.bundle
-/vendor/bundle
-/log/*
-/tmp/*
-/db/*.sqlite3
-/public/system/*
-/coverage/
-/spec/tmp/*
-**.orig
-rerun.txt
-pickle-email-*.html
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0

Gemfile

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

LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Xuhao
+
+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.

README.md

@@ -1,4 +1,82 @@
-china_aqi
-=========
+# ChinaAqi
 
-China AQI API from PM25.in
+China Air Quality Index API for Rails.
+
+Thanks [pm25.in][pm25_in] for provide all the AQI sources for us as free, all the data is form China's official sector. it's a reall gread work!
+
+ChinaAqi gem provide some interface base on Ruby On Rails, before to use it, you need ask for a token form [pm25.in][pm25_in_api].
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'china_aqi'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install china_aqi
+
+Run install generator:
+
+    $ rails generate china_aqi:install
+
+It will create file: config/initializers/china_aqi.rb
+
+## Usage
+
+As we mention at the beginning, we must get a token form [pm25.in][pm25_in_api] before we use their APIs, it's free!
+
+Once you get the token, put it in config/initializers/china_aqi.rb, then enjoy!
+
+Most AQI data are available, they are:
+
+  - **co**: 一氧化碳
+  - **no2**: 二氧化氮
+  - **o3**: 臭氧
+  - **pm10**: 颗粒物（粒径小于等于10μm）
+  - **pm2.5**: 颗粒物（粒径小于等于2.5μm）
+  - **so2**: 二氧化硫
+
+All monitoring stations in most cities of China are available.
+
+### Examples
+
+    # City name can be Chinese characters, pinyin and area code
+    # params:
+    #  avg: if true,return average for all monitoring stations, default is true
+    #  stations: if yes, return data for all monitoring stations; if no, just return average.
+
+    shanghai = ChinaAqi::PM25.new('上海')  # #<ChinaAqi::PM25:0x007fe2a631aef8 @city="上海" ...
+    shanghai.get                          # [{"aqi"=>74, "area"=>"上海", "pm2_5"=>48 ...
+    ChinaAqi::PM25.new('021', avg: true, stations: :yes).get # Same as above.
+
+
+    # Get so2 data for Shanghai
+    ChinaAqi::SO2.new('shanghai', avg: true, stations: :no).get # [{"aqi"=>74, "area"=> ...
+
+    # Get all data for one stations with code "1141A"
+    ChinaAqi::Station.new('1141A').get  # [{"aqi"=>75, "area"=>"上海", "co"=>0.0, ...
+
+    # Get all data that the API provide, never use it unless you have to.
+    ChinaAqi::Global.new.get # [{"aqi"=>144, "area"=>"天津"
+
+### Helpers
+
+    # get station names and station codes for one city
+    ChinaAqi.get_stations_for_city('上海')  # {"city"=>"上海", "stations"=>[{"station_name"=>"普陀"
+
+## Contributing
+
+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 new Pull Request
+
+
+[pm25_in]: http://www.pm25.in
+[pm25_in_api]: http://www.pm25.in/api_doc

Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

china_aqi.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'china_aqi/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "china_aqi"
+  spec.version       = ChinaAqi::VERSION
+  spec.authors       = ["Xuhao"]
+  spec.email         = ["xuhao@rubyfans.com"]
+  spec.description   = %q{China AQI API from PM25.in}
+  spec.summary       = %q{China AQI API from PM25.in}
+  spec.homepage      = "https://github.com/Xuhao/china_aqi"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  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_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_dependency 'httparty'
+end

lib/ exceptions.rb

@@ -0,0 +1,4 @@
+module ChinaAqi
+  class TokenMissingError < StandardError; end
+  class NotImplementedError < StandardError; end
+end

lib/china_aqi.rb

@@ -0,0 +1,9 @@
+require "china_aqi/version"
+
+module ChinaAqi
+  mattr_accessor :token, instance_accessor: false
+end
+
+require 'china_aqi/exceptions'
+require 'china_aqi/base'
+require 'china_aqi/city_stations'

lib/china_aqi/aqi/city.rb

@@ -0,0 +1,6 @@
+module ChinaAqi
+  # Fetch simple data for all monitoring stations in one city
+  class City < Base
+    self.method = :only_aqi
+  end
+end

lib/china_aqi/aqi/city_pro.rb

@@ -0,0 +1,6 @@
+module ChinaAqi
+  # Fetch detail data for all monitoring stations in one city
+  class CityPro < Base
+    self.method = :aqi_details
+  end
+end

lib/china_aqi/aqi/co.rb

@@ -0,0 +1,5 @@
+module ChinaAqi
+  class CO < Base
+    self.method = :co
+  end
+end

lib/china_aqi/aqi/global.rb

@@ -0,0 +1,14 @@
+module ChinaAqi
+  # All data
+  # This class is used for fetch data for all cities in china.
+  # It will return a very big array, don't use it unless you have to！
+  class Global < Base
+    self.method = :all_cities
+
+    def initialize
+      raise TokenMissingError, 'Token is missing, please set token first!' if ChinaAqi.token.blank?
+      @token = ChinaAqi.token
+      @parmas = { token: ChinaAqi.token }
+    end
+  end
+end

lib/china_aqi/aqi/no2.rb

@@ -0,0 +1,5 @@
+module ChinaAqi
+  class NO2 < Base
+    self.method = :no2
+  end
+end

lib/china_aqi/aqi/o3.rb

@@ -0,0 +1,5 @@
+module ChinaAqi
+  class O3 < Base
+    self.method = :o3
+  end
+end

lib/china_aqi/aqi/pm10.rb

@@ -0,0 +1,5 @@
+module ChinaAqi
+  class PM10 < Base
+    self.method = :pm10
+  end
+end

lib/china_aqi/aqi/pm25.rb

@@ -0,0 +1,5 @@
+module ChinaAqi
+  class PM25 < Base
+    self.method = :pm2_5
+  end
+end

lib/china_aqi/aqi/so2.rb

@@ -0,0 +1,5 @@
+module ChinaAqi
+  class SO2 < Base
+    self.method = :so2
+  end
+end

lib/china_aqi/aqi/station.rb

@@ -0,0 +1,26 @@
+module ChinaAqi
+  # Fetch data for one monitoring station
+  #
+  # example:
+  #
+  #   ChinaAqi::Station.new('1141A').get
+  #
+  # You can get all station codes for one city like this:
+  #
+  #   ChinaAqi::CityStations.new(city_name).get
+  #
+  # or like this:
+  #
+  #   ChinaAqi.get_stations_for_city(city)
+  class Station < Base
+    self.method = :aqis_by_station
+    attr_accessor :station_code
+
+    def initialize(station_code)
+      raise TokenMissingError, 'Token is missing, please set token first!' if ChinaAqi.token.blank?
+      @station_code = station_code
+      @token = ChinaAqi.token
+      @parmas = { station_code: station_code, token: ChinaAqi.token }
+    end
+  end
+end

lib/china_aqi/base.rb

@@ -0,0 +1,52 @@
+require 'china_aqi/utility'
+module ChinaAqi
+  # Fetch data with different method
+  # 
+  # Pass city name and params those API accept.
+  #
+  #  shanghai = ChinaAqi::PM25.new('city_name', params = { avg: true/false, stations: :yes/:no })
+  #
+  #  params:
+  #    avg: if true,return average for all monitoring stations, default is true
+  #    stations: if yes, return data for all monitoring stations; if no, just return average.
+  #
+  #  checkout explanation in http://www.pm25.in/api_doc
+  #
+  # examples
+  #
+  #     shanghai = ChinaAqi::PM25.new('上海')  # #<ChinaAqi::PM25:0x007fe2a631aef8 @city="上海"...
+  #     shanghai.get                           # [{"aqi"=>74, "area"=>"上海", "pm2_5"=>48,...
+  #
+  #     # Get so2 data for 上海
+  #     ChinaAqi::SO2.new('上海', avg: false, stations: :no).get  # [{"aqi"=>74, "area"=>"上海", "pm2_5"=>48,...
+  #
+  #     # Get all data for one stations with code "1141A"
+  #     ChinaAqi::Station.new('1141A').get  # [{"aqi"=>75, "area"=>"上海", "co"=>0.0, "co_24h"=>0.0
+  #
+  #     # Get all data that the API provide
+  #     ChinaAqi::Global.new.get
+  #
+  class Base
+    include ChinaAqi::Utility
+
+    attr_accessor :city
+
+    def initialize(city, querys = {avg: true, stations: :yes})
+      raise TokenMissingError, 'Token is missing, please set token first!' if ChinaAqi.token.blank?
+      @city = city
+      @parmas = querys.merge(city: city, token: ChinaAqi.token)
+      @token = ChinaAqi.token
+    end
+  end
+end
+
+require 'china_aqi/aqi/city'
+require 'china_aqi/aqi/city_pro'
+require 'china_aqi/aqi/co'
+require 'china_aqi/aqi/global'
+require 'china_aqi/aqi/no2'
+require 'china_aqi/aqi/o3'
+require 'china_aqi/aqi/pm10'
+require 'china_aqi/aqi/pm25'
+require 'china_aqi/aqi/so2'
+require 'china_aqi/aqi/station'

lib/china_aqi/city_stations.rb

@@ -0,0 +1,23 @@
+require 'china_aqi/utility'
+module ChinaAqi
+  # All monitoring station names in one city
+  class CityStations
+    include ChinaAqi::Utility
+    
+    self.method = :station_names
+
+    def initialize(city)
+      raise TokenMissingError, 'Token is missing, please set token first!' if ChinaAqi.token.blank?
+      @city = city
+      @token = ChinaAqi.token
+      @parmas = { city: city, token: ChinaAqi.token }
+    end
+  end
+
+  # create a helper in ChinaAqi module
+  def get_stations_for_city(city)
+    CityStations.new(city).get
+  end
+  
+  module_function :get_stations_for_city
+end

lib/china_aqi/exceptions.rb

@@ -0,0 +1,4 @@
+module ChinaAqi
+  class TokenMissingError < StandardError; end
+  class NotImplementedError < StandardError; end
+end