civic_aide 0.0.1

data/Rakefile

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

data/civic_aide.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'civic_aide/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "civic_aide"
+  spec.version       = CivicAide::VERSION
+  spec.authors       = ["Tyler Pearson"]
+  spec.email         = ["ty.pearson@gmail.com"]
+  spec.summary       = %q{A Ruby wrapper for the Google Civic Information API}
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/tylerpearson/civic_aide"
+  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", "~> 10.1.1"
+  spec.add_development_dependency "rspec", "~> 2.14.1"
+  spec.add_development_dependency "vcr", '~> 2.5.0'
+  spec.add_development_dependency "webmock", '1.13.0'
+
+  spec.add_runtime_dependency "httparty"
+  spec.add_runtime_dependency "hashie"
+end

data/lib/civic_aide.rb

@@ -0,0 +1,34 @@
+require 'forwardable'
+require 'hashie'
+require 'civic_aide/version'
+require 'civic_aide/client'
+require 'civic_aide/hash'
+require 'civic_aide/string'
+require 'civic_aide/elections'
+require 'civic_aide/representatives'
+require 'civic_aide/errors'
+
+module CivicAide
+  class << self
+    extend Forwardable
+
+    def api_key
+      raise APIKeyNotSet if @api_key.nil?
+      @api_key
+    end
+
+    def api_key=(api_key)
+      @api_key = api_key
+    end
+
+    delegate [
+      :elections,
+      :representatives
+    ] => :client
+
+    def client
+      @client = CivicAide::Client.new(@api_key)
+    end
+
+  end
+end

data/lib/civic_aide/client.rb

@@ -0,0 +1,71 @@
+require 'httparty'
+require 'forwardable'
+
+module CivicAide
+  class Client
+    extend Forwardable
+
+    include HTTParty
+
+    API_ENDPOINT = 'https://www.googleapis.com/civicinfo/'
+    API_VERSION = 'us_v1'
+
+    base_uri "#{API_ENDPOINT}#{API_VERSION}"
+    headers  "Content-Type" => "application/json"
+    headers  "User-Agent" => "CivicAide Ruby gem v#{CivicAide::VERSION}".freeze
+
+    attr_reader :api_key
+
+    def initialize(api_key=nil)
+      @api_key = api_key
+      @api_key ||= CivicAide.api_key
+    end
+
+    def get(url, query={})
+      response = self.class.get(url, :query => query.merge(self.default_query))
+      format_response(response.body)
+    end
+
+    def post(url, query={}, body={})
+      response = self.class.post(url,
+          :query => query.merge(self.default_query),
+          :body => body.to_json
+        )
+      check_response_status(response['status'])
+      format_response(response.body)
+    end
+
+    def elections(election_id=nil)
+      CivicAide::Elections.new(self, election_id)
+    end
+
+    def representatives
+      CivicAide::Representatives.new(self)
+    end
+
+    protected
+
+      def default_query
+        {:key => @api_key, :prettyPrint => false}
+      end
+
+      def format_response(body)
+        body = JSON.parse(body)
+        body.change_zip! # to prevent Array#zip clashing when rubifying the keys
+        body.rubyify_keys!
+        Hashie::Mash.new(body)
+      end
+
+      def check_response_status(code)
+        unless code.downcase == "success"
+          error_type = classify_error(code)
+          raise error_type
+        end
+      end
+
+      def classify_error(code)
+        code.slice(0,1).capitalize + code.slice(1..-1)
+      end
+
+  end
+end

data/lib/civic_aide/elections.rb

@@ -0,0 +1,22 @@
+module CivicAide
+  class Elections
+    attr_reader :client, :election_id
+
+    def initialize(client, election_id=nil)
+      @client = client
+      @election_id = election_id
+    end
+
+    def all
+      response = client.get('/elections')
+      response.except!(:kind)
+    end
+
+    def at(address)
+      raise ElectionIdMissing, "Missing a required election id" if @election_id.nil?
+      response = client.post("/voterinfo/#{election_id}/lookup", {officialOnly: false}, {:address => address})
+      response.except!(:kind, :status)
+    end
+
+  end
+end

data/lib/civic_aide/errors.rb

@@ -0,0 +1,56 @@
+class APIError < StandardError; end
+
+class APIKeyNotSet < StandardError
+  def initialize(msg = "Missing a required Google API key.")
+    super
+  end
+end
+
+class ElectionIdMissing < StandardError
+  def initialize(msg = "Missing a required election id.")
+    super
+  end
+end
+
+class NoStreetSegmentFound < APIError
+  def initialize(msg = "The API currently has no information about what electoral precinct and/or district this address belongs to. It may be that we are still sourcing/processing new data, or that there are no voters who have registered to vote at this address.")
+    super
+  end
+end
+
+class AddressUnparseable < APIError
+  def initialize(msg = "The requested address is not formatted correctly or cannot be geocoded (i.e. the Google Maps API does not know anything about this address).")
+    super
+  end
+end
+
+class NoAddressParameter < APIError
+  def initialize(msg = "No address was provided.")
+    super
+  end
+end
+
+class MultipleStreetSegmentsFound < APIError
+  def initialize(msg = "The API cannot find information for the specified address, but it has information about nearby addresses. The user should contact their election official for more information.")
+    super
+  end
+end
+
+class ElectionOver < APIError
+  def initialize(msg = "The requested election is over. API results for the election are no longer available. Make an electionQuery to find an id for an upcoming election.")
+    super
+  end
+end
+
+class ElectionUnknown < APIError
+  def initialize(msg = "The requested election id is invalid. Make an electionQuery to find a valid id.")
+    super
+  end
+end
+
+class InternalLookupFailure < APIError
+  def initialize(msg = "An unspecified error occurred processing the request.")
+    super
+  end
+end
+

data/lib/civic_aide/hash.rb

@@ -0,0 +1,36 @@
+class Hash
+
+  def rubyify_keys!
+    keys.each do |k|
+      val = self[k]
+      # ignore Open Civic Data identifiers
+      unless k[0..3] == "ocd-"
+        delete(k)
+        new_key = k.to_s.underscore
+        self[new_key] = val
+      end
+      val.rubyify_keys! if val.is_a?(Hash)
+      val.each{|p| p.rubyify_keys! if p.is_a?(Hash)} if val.is_a?(Array)
+    end
+    self
+  end
+
+  def except(*keys)
+    dup.except!(*keys)
+  end
+
+  def except!(*keys)
+    keys.each { |key| delete(key) }
+    self
+  end
+
+  def change_zip!
+    keys.each do |k|
+      self["zipCode"] = self.delete "zip"  if k == "zip"
+      self[k].change_zip! if self[k].is_a? Hash
+      self[k].each{|p| p.change_zip! if p.is_a?(Hash)} if self[k].is_a?(Array)
+    end
+    self
+  end
+
+end

data/lib/civic_aide/representatives.rb

@@ -0,0 +1,16 @@
+module CivicAide
+  class Representatives
+    attr_reader :client, :include_offices
+
+    def initialize(client)
+      @client = client
+      @include_offices = true
+    end
+
+    def at(address)
+      response = client.post("/representatives/lookup", {includeOffices: @include_offices}, {:address => address})
+      response.except!(:kind, :status)
+    end
+
+  end
+end

data/lib/civic_aide/string.rb

@@ -0,0 +1,9 @@
+class String
+  def underscore
+    self.gsub(/::/, '/').
+    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+    tr("-", "_").
+    downcase
+  end
+end

data/lib/civic_aide/version.rb

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

data/spec/civic_aide/client_spec.rb

@@ -0,0 +1,62 @@
+require 'spec_helper'
+
+describe CivicAide::Client do
+
+  before do
+    @client = CivicAide::Client.new("AIzaSyDWJSisG_4Azd6nVJTU5gdKPiKKTCovupY")
+  end
+
+  describe '.new' do
+    it 'raises an error with no API key' do
+      expect{ CivicAide::Client.new }.to raise_error(APIKeyNotSet)
+    end
+
+    it "doesn't raise an error with class API key set" do
+      CivicAide.api_key = "AIzaSyDWJSisG_4Azd6nVJTU5gdKPiKKTCovupY"
+      expect{ CivicAide::Client.new }.to_not raise_error
+    end
+  end
+
+  describe "#new" do
+    it "takes one parameter and returns a Client object" do
+      @client.should be_an_instance_of CivicAide::Client
+    end
+  end
+
+  describe 'configuration' do
+    it 'should have correct API endpoint' do
+      expect(CivicAide::Client::API_ENDPOINT).to eq('https://www.googleapis.com/civicinfo/')
+    end
+
+    it 'should have the correct API version' do
+      expect(CivicAide::Client::API_VERSION).to eq('us_v1')
+    end
+
+    it 'should include HTTParty' do
+      @client.extend(HTTParty)
+    end
+
+    it 'should have the correct base_uri' do
+      expect(CivicAide::Client.base_uri).to eq('https://www.googleapis.com/civicinfo/us_v1')
+    end
+  end
+
+  describe '#default_query' do
+    it 'should have the api key' do
+      @client.send(:default_query).should == {:key => @client.api_key, :prettyPrint => false}
+    end
+  end
+
+  describe "#elections" do
+    it "should be the right class" do
+      expect(@client.elections).to be_an_instance_of CivicAide::Elections
+    end
+  end
+
+  describe "#representatives" do
+    it "should be the right class" do
+      expect(@client.representatives).to be_an_instance_of CivicAide::Representatives
+    end
+  end
+
+end

data/spec/civic_aide/elections_spec.rb

@@ -0,0 +1,130 @@
+require 'spec_helper'
+
+describe CivicAide::Elections do
+
+  before do
+    @client = CivicAide::Client.new("AIzaSyDWJSisG_4Azd6nVJTU5gdKPiKKTCovupY")
+  end
+
+  describe "get all elections" do
+
+    let(:info) { @client.elections.all }
+
+    before do
+      VCR.insert_cassette 'elections/all', :record => :new_episodes
+      @election = info.elections.first
+    end
+
+    after do
+      VCR.eject_cassette
+    end
+
+    it "must parse the response from JSON to Hash" do
+      expect(info).to be_a Hash
+    end
+
+    it "should have elections" do
+      expect(info).to respond_to(:elections)
+    end
+
+    it "should have multiple elections" do
+      info.elections.should_not be_empty
+    end
+
+    it "should have an id" do
+      expect(@election.id).to eq("2000")
+    end
+
+    it "should have a name" do
+      expect(@election.name).to eq("VIP Test Election")
+    end
+
+    it "should have an election day" do
+      expect(@election.election_day).to eq("2015-06-06")
+    end
+
+  end
+
+  describe "get info for specific election" do
+
+    let(:info) { @client.elections(4015).at('4910 Willet Drive, Annandale, VA 22003') }
+
+    before do
+      VCR.insert_cassette 'elections/single', :record => :new_episodes
+    end
+
+    after do
+      VCR.eject_cassette
+    end
+
+    it "must parse the response from JSON to Hash" do
+      expect(info).to be_a Hash
+    end
+
+    it "should have an election" do
+      expect(info.election).to be_a Hash
+    end
+
+    it "should have an election id" do
+      expect(info.election.id).to eq("4015")
+    end
+
+    it "should have an election name" do
+      expect(info.election.name).to eq("VA State Election")
+    end
+
+    it "should have an election day" do
+      expect(info.election.election_day).to eq("2013-11-05")
+    end
+
+    it "should have normalized input" do
+      expect(info).to respond_to(:normalized_input)
+    end
+
+    it "should have normalized input hash" do
+      expect(info.normalized_input).to be_a Hash
+    end
+
+    it "should have normalized input line 1" do
+      expect(info.normalized_input.line1).to eq("4910 willet dr")
+    end
+
+    it "should have normalized input city" do
+      expect(info.normalized_input.city).to eq("annandale")
+    end
+
+    it "should have normalized input state" do
+      expect(info.normalized_input.state).to eq("VA")
+    end
+
+    it "should have normalized input zip" do
+      expect(info.normalized_input.zip_code).to eq("22003")
+    end
+
+    it "should have contests" do
+      expect(info).to respond_to(:contests)
+    end
+
+    it "should have contests as array" do
+      expect(info.contests).to be_a Array
+    end
+
+    it "should have candidates" do
+      expect(info.contests[0]).to respond_to(:candidates)
+    end
+
+    it "should have candidates array" do
+      expect(info.contests[0].candidates).to be_a Array
+    end
+
+    it "should have sources" do
+      expect(info.contests[0]).to respond_to(:sources)
+    end
+
+    it "should have sources array" do
+      expect(info.contests[0].sources).to be_a Array
+    end
+
+  end
+
+end