geocodio-ocd 1.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c9199f7869e69da03015cf1880392b7850d05485fcb121e3ce019bdf7a21add9
+  data.tar.gz: dd5b48ccd480bf03f505a9fe49553966c9f1fe09f2ff443db50f27eef3db1e3c
+SHA512:
+  metadata.gz: c411d98acf8ffd2a498fcbec82670f5995285b638db230027eace6ebec0403e769d5f16f93834b31a9f82afcad63ab36170fb65282f8bbb6453a232ecc502807
+  data.tar.gz: d165d5e4169ff699f4c1ac099ac17cdca76580a307034224eb1e1698563e3876f64394d437b3a0599848f86b7b341e72ff69b85a6e61c9df270140b49e4153c1

data/lib/geocodio/address.rb

@@ -0,0 +1,114 @@
+require 'geocodio/congressional_district'
+require 'geocodio/school_district'
+require 'geocodio/state_legislative_district'
+require 'geocodio/timezone'
+require 'geocodio/canadian/electoral_districts'
+
+module Geocodio
+  class Address
+    include Geocodio::Canadian
+    attr_reader :number, :predirectional, :street, :suffix, :postdirectional,
+                :formatted_street, :city, :state, :zip, :county
+
+    attr_reader :latitude, :longitude
+    alias :lat :latitude
+    alias :lng :longitude
+
+    attr_reader :congressional_districts, :house_districts, :senate_districts,
+                :unified_school_district, :elementary_school_district,
+                :secondary_school_district
+
+    attr_reader :timezone
+
+    # How accurate geocod.io deemed this result to be given the original query.
+    #
+    # @return [Float] a number between 0 and 1
+    attr_reader :accuracy, :accuracy_type, :source
+
+    def initialize(payload = {})
+      set_attributes(payload['address_components']) if payload['address_components']
+      set_coordinates(payload['location'])          if payload['location']
+      set_additional_fields(payload['fields'])      if payload['fields']
+
+      @source            = payload['source']
+      @accuracy          = payload['accuracy']
+      @accuracy_type     = payload['accuracy_type']
+      @formatted_address = payload['formatted_address']
+    end
+
+    # Formats the address in the standard way.
+    #
+    # @return [String] a formatted address
+    def to_s
+      @formatted_address
+    end
+
+    private
+
+    def set_attributes(attributes)
+      @number           = attributes['number']
+      @predirectional   = attributes['predirectional']
+      @street           = attributes['street']
+      @suffix           = attributes['suffix']
+      @postdirectional  = attributes['postdirectional']
+      @formatted_street = attributes['formatted_street']
+      @city             = attributes['city']
+      @state            = attributes['state']
+      @zip              = attributes['zip']
+      @county           = attributes['county']
+    end
+
+    def set_coordinates(coordinates)
+      @latitude  = coordinates['lat']
+      @longitude = coordinates['lng']
+    end
+
+    def set_additional_fields(fields)
+      set_congressional_districts(fields['congressional_districts'])   if fields['congressional_districts']
+      set_legislative_districts(fields['state_legislative_districts']) if fields['state_legislative_districts']
+      set_school_districts(fields['school_districts'])                 if fields['school_districts']
+      set_timezone(fields['timezone'])                                 if fields['timezone']
+      
+      riding, provincial_riding = fields.values_at('riding', 'provincial_riding')
+      if riding || provincial_riding
+        set_canadian_fields(riding, provincial_riding)
+      end
+    end
+
+    def set_congressional_districts(districts)
+      return if districts.empty?
+        
+      @congressional_districts = districts.map { |district| CongressionalDistrict.new(district) }
+    end
+
+    def set_legislative_districts(districts)
+      return if districts.empty?
+      @house_districts, @senate_districts = districts.values_at('house', 'senate').map do |district_entries|
+        [*district_entries].map{|entry|  StateLegislativeDistrict.new(entry)}
+      end
+    end
+
+    def set_school_districts(schools)
+      return if schools.empty?
+
+      if schools['unified']
+        @unified_school_district = SchoolDistrict.new(schools['unified'])
+      else
+        @elementary_school_district = SchoolDistrict.new(schools['elementary']) if schools['elementary']
+        @secondary_school_district = SchoolDistrict.new(schools['secondary']) if schools['secondary']
+      end
+    end
+
+    def set_timezone(timezone)
+      return if timezone.empty?
+
+      @timezone = Timezone.new(timezone)
+    end
+
+    def <=>(address)
+      return -1 if self.accuracy <  address.accuracy
+      return  0 if self.accuracy == address.accuracy
+      return  1 if self.accuracy >  address.accuracy
+    end
+  end
+end

data/lib/geocodio/address_set.rb

@@ -0,0 +1,48 @@
+# AddressSet is a collection of Geocodio::Address objects that get returned from
+# a query to geocod.io. Because one query can return multiple results, each with
+# an accuracy, a collection to manage them is needed. Most of the time, the user
+# should only need to use the #best method.
+module Geocodio
+  class AddressSet
+    include Enumerable
+
+    # Returns the query that retrieved this result set.
+    #
+    # @return [String] the original query
+    attr_reader :query
+
+    def initialize(query, *addresses, input: nil)
+      @query           = query
+      @addresses       = addresses
+      @formatted_input = input
+    end
+
+    def each(&block)
+      @addresses.each(&block)
+    end
+
+    # Returns the result that geocod.io deemed the most accurate for the query.
+    #
+    # @return [Geocodio::Address] the most accurate address
+    def best
+      best = @addresses.find { |address| address.to_s == @formatted_input }
+      return best if best
+
+      max_by(&:accuracy)
+    end
+
+    # Returns the number of addresses contained in this result set.
+    #
+    # @return [Integer] the number of addresses
+    def size
+      @addresses.size
+    end
+
+    # Returns whether or not there are any addresses in this result set.
+    #
+    # @return [Boolean] if there were any results returned by Geocodio
+    def empty?
+      @addresses.empty?
+    end
+  end
+end

data/lib/geocodio/canadian/electoral_district_base.rb

@@ -0,0 +1,21 @@
+module Geocodio
+  module Canadian
+    class ElectoralDistrictBase
+      attr_accessor :ocd_id
+      attr_accessor :name_french
+      attr_accessor :name_english
+      attr_accessor :source
+
+      def initialize(payload = {})
+        @ocd_id          = payload['ocd_id']
+        @name_english    = payload['name_english']
+        @name_french     = payload['name_french']
+        @source          = payload['source']
+      end
+
+      def name
+        @name_english
+      end
+    end
+  end
+end

data/lib/geocodio/canadian/electoral_districts.rb

@@ -0,0 +1,23 @@
+require 'geocodio/canadian/electoral_district_base'
+require 'geocodio/canadian/federal_electoral_district'
+require 'geocodio/canadian/provincial_electoral_district'
+
+module Geocodio
+  module Canadian
+    class ElectoralDistricts
+      attr_accessor :federal_electoral_district
+      attr_accessor :provincial_electoral_district
+      
+      def initialize(riding, provincial_riding)
+
+        if riding && riding.is_a?(Hash) && riding.size > 0
+          @federal_electoral_district = FederalElectoralDistrict.new(riding)
+        end
+        
+        if provincial_riding && provincial_riding.is_a?(Hash) && provincial_riding.size > 0
+          @provincial_electoral_district = ProvincialElectoralDistrict.new(provincial_riding)
+        end
+      end
+    end
+  end
+end

data/lib/geocodio/canadian/federal_electoral_district.rb

@@ -0,0 +1,12 @@
+module Geocodio
+  module Canadian
+    class FederalElectoralDistrict < ElectoralDistrictBase
+      attr_accessor :code
+      
+      def initialize(payload = {})
+        super
+        @code = payload['code']
+      end
+    end
+  end
+end

data/lib/geocodio/canadian/provincial_electoral_district.rb

@@ -0,0 +1,6 @@
+module Geocodio
+  module Canadian
+    class ProvincialElectoralDistrict < ElectoralDistrictBase
+    end
+  end
+end

data/lib/geocodio/canadian.rb

@@ -0,0 +1,14 @@
+module Geocodio
+  module Canadian
+    attr_reader :canadian
+    
+    def set_canadian_fields(riding, provincial_riding)
+      @canadian = ElectoralDistricts.new(riding, provincial_riding)
+    end
+
+    def canadian?
+      !!@canadian
+    end
+
+  end
+end

data/lib/geocodio/client/error.rb

@@ -0,0 +1,15 @@
+module Geocodio
+  class Client
+    class Error < RuntimeError
+      attr_reader :response
+
+      def initialize(response)
+        @response, @json = response, JSON.parse(response.body)
+      end
+
+      def body() @json end
+      def message() body['error'] end
+      alias :error :message
+    end
+  end
+end

data/lib/geocodio/client/response.rb

@@ -0,0 +1,13 @@
+require 'json'
+
+module Geocodio
+  class Client
+    class Response
+      attr_reader :body
+
+      def initialize(response)
+        @body = JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/geocodio/client.rb

@@ -0,0 +1,155 @@
+require 'net/http'
+require 'json'
+require 'cgi'
+
+require 'geocodio/client/error'
+require 'geocodio/client/response'
+require 'geocodio/utils'
+
+module Geocodio
+  class Client
+    include Geocodio::Utils
+
+    CONTENT_TYPE = 'application/json'
+    METHODS = {
+      :get    => Net::HTTP::Get,
+      :post   => Net::HTTP::Post,
+      :put    => Net::HTTP::Put,
+      :delete => Net::HTTP::Delete
+    }
+    HOST = 'api.geocod.io'
+    BASE_PATH = '/v1.7'
+    PORT = 80
+
+    def initialize(api_key = ENV['GEOCODIO_API_KEY'])
+      @api_key = api_key
+    end
+
+    # Geocodes one or more addresses. If one address is specified, a GET request
+    # is submitted to http://api.geocod.io/v1/geocode. Multiple addresses will
+    # instead submit a POST request.
+    #
+    # @param [Array<String>] addresses one or more String addresses
+    # @param [Hash] options an options hash
+    # @option options [Array] :fields a list of option fields to request (possible: "cd" or "cd113", "stateleg", "school", "timezone")
+    # @return [Geocodio::Address, Array<Geocodio::AddressSet>] One or more Address Sets
+    def geocode(addresses, options = {})
+      if addresses.size < 1
+        raise ArgumentError, 'You must provide at least one address to geocode.'
+      elsif addresses.size == 1
+        geocode_single(addresses.first, options)
+      else
+        geocode_batch(addresses, options)
+      end
+    end
+
+    # Reverse geocodes one or more pairs of coordinates. Coordinate pairs may be
+    # specified either as a comma-separated "latitude,longitude" string, or as
+    # a Hash with :lat/:latitude and :lng/:longitude keys. If one pair of
+    # coordinates is specified, a GET request is submitted to
+    # http://api.geocod.io/v1/reverse. Multiple pairs of coordinates will
+    # instead submit a POST request.
+    #
+    # @param [Array<String>, Array<Hash>] coordinates one or more pairs of coordinates
+    # @param [Hash] options an options hash
+    # @option options [Array] :fields a list of option fields to request (possible: "cd" or "cd113", "stateleg", "school", "timezone")
+    # @return [Geocodio::Address, Array<Geocodio::AddressSet>] One or more Address Sets
+    def reverse_geocode(coordinates, options = {})
+      if coordinates.size < 1
+        raise ArgumentError, 'You must provide coordinates to reverse geocode.'
+      elsif coordinates.size == 1
+        reverse_geocode_single(coordinates.first, options)
+      else
+        reverse_geocode_batch(coordinates, options)
+      end
+    end
+    alias :reverse :reverse_geocode
+
+    # Sends a GET request to http://api.geocod.io/v1/parse to correctly dissect
+    # an address into individual parts. As this endpoint does not do any
+    # geocoding, parts missing from the passed address will be missing from the
+    # result.
+    #
+    # @param address [String] the full or partial address to parse
+    # @return [Geocodio::Address] a parsed and formatted Address
+    def parse(address, options = {})
+      params, options = normalize_params_and_options(options)
+      params[:q] = address
+
+      Address.new get('/parse', params, options).body
+    end
+
+    private
+
+      METHODS.each do |method, _|
+        define_method(method) do |path, params = {}, options = {}|
+          request method, path, options.merge(params: params)
+        end
+      end
+
+      def geocode_single(address, options = {})
+        params, options = normalize_params_and_options(options)
+        params[:q] = address
+
+        response  = get '/geocode', params, options
+        addresses, input = parse_results(response)
+
+        AddressSet.new(address, *addresses, input: input)
+      end
+
+      def reverse_geocode_single(pair, options = {})
+        params, options = normalize_params_and_options(options)
+        pair = normalize_coordinates(pair)
+        params[:q] = pair
+
+        response  = get '/reverse', params, options
+        addresses, input = parse_results(response)
+
+        AddressSet.new(pair, *addresses, input: input)
+      end
+
+      def geocode_batch(addresses, options = {})
+        params, options = normalize_params_and_options(options)
+        options[:body] = addresses
+
+        response = post '/geocode', params, options
+
+        parse_nested_results(response)
+      end
+
+      def reverse_geocode_batch(pairs, options = {})
+        params, options = normalize_params_and_options(options)
+        options[:body] = pairs.map { |pair| normalize_coordinates(pair) }
+
+        response = post '/reverse', params, options
+
+        parse_nested_results(response)
+      end
+
+      def request(method, path, options)
+        path += "?api_key=#{@api_key}"
+
+        if params = options[:params] and !params.empty?
+          q = params.map { |k, v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }
+          path += "&#{q.join('&')}"
+        end
+        
+        req = METHODS[method].new(BASE_PATH + path, 'Accept' => CONTENT_TYPE)
+
+        if options.key?(:body)
+          req['Content-Type'] = CONTENT_TYPE
+          req.body = options[:body] ? JSON.dump(options[:body]) : ''
+        end     
+        http = Net::HTTP.new HOST, PORT
+        http.read_timeout = options[:timeout] if options[:timeout]
+        res  = http.start { http.request(req) }
+
+        case res
+        when Net::HTTPSuccess
+          return Response.new(res)
+        else
+          raise Error, res
+        end
+      end
+  end
+end

data/lib/geocodio/congressional_district.rb

@@ -0,0 +1,30 @@
+require 'geocodio/legislator'
+
+module Geocodio
+  class CongressionalDistrict
+    attr_reader :name
+    attr_reader :district_number
+    attr_reader :congress_number
+    attr_reader :proportion
+    attr_reader :current_legislators
+    attr_accessor :ocd_id
+
+    def initialize(payload = {})
+      @name            = payload['name']
+      @district_number = payload['district_number'].to_i
+      @congress_number = payload['congress_number'].to_i
+      @congress_years  = payload['congress_years']
+      @proportion      = payload['proportion'].to_i
+      @ocd_id          = payload['ocd_id']
+      
+      @current_legislators = [*payload['current_legislators']].map do |legislator|
+        Legislator.new(legislator)
+      end
+    end
+
+    def congress_years
+      first, last = @congress_years.split('-').map(&:to_i)
+      first..last
+    end
+  end
+end

data/lib/geocodio/legislator.rb

@@ -0,0 +1,69 @@
+module Geocodio
+  class Legislator
+    attr_reader :type
+    attr_reader :name
+    attr_reader :birthday
+    attr_reader :gender
+    attr_reader :party
+    attr_reader :url
+    attr_reader :address
+    attr_reader :phone
+    attr_reader :contact_form
+    attr_reader :rss_url
+    attr_reader :twitter
+    attr_reader :facebook
+    attr_reader :youtube
+    attr_reader :youtube_id
+    attr_reader :bioguide_id
+    attr_reader :thomas_id
+    attr_reader :opensecrets_id
+    attr_reader :lis_id
+    attr_reader :cspan_id
+    attr_reader :govtrack_id
+    attr_reader :votesmart_id
+    attr_reader :ballotpedia_id
+    attr_reader :washington_post_id
+    attr_reader :icpsr_id
+    attr_reader :wikipedia_id
+
+    def initialize(payload = {})
+      @type = payload['type']
+
+      if payload['bio']
+        @name = "#{payload['bio']['first_name']} #{payload['bio']['last_name']}"
+        @birthday = Date.new(*payload['bio']['birthday'].split('-').map(&:to_i))
+        @gender = payload['bio']['gender']
+        @party = payload['bio']['party']
+      end
+
+      if payload['contact']
+        @url          = payload['contact']['url']
+        @address      = payload['contact']['address']
+        @phone        = payload['contact']['phone']
+        @contact_form = payload['contact']['contact_form']
+      end
+
+      if payload['social']
+        @rss_url    = payload['social']['rss_url']
+        @twitter    = payload['social']['twitter']
+        @facebook   = payload['social']['facebook']
+        @youtube    = payload['social']['youtube']
+        @youtube_id = payload['social']['youtube_id']
+      end
+
+      if payload['references']
+        @bioguide_id        = payload['references']['bioguide_id']
+        @thomas_id          = payload['references']['thomas_id']
+        @opensecrets_id     = payload['references']['opensecrets_id']
+        @lis_id             = payload['references']['lis_id']
+        @cspan_id           = payload['references']['cspan_id']
+        @govtrack_id        = payload['references']['govtrack_id']
+        @votesmart_id       = payload['references']['votesmart_id']
+        @ballotpedia_id     = payload['references']['ballotpedia_id']
+        @washington_post_id = payload['references']['washington_post_id']
+        @icpsr_id           = payload['references']['icpsr_id']
+        @wikipedia_id       = payload['references']['wikipedia_id']
+      end
+    end
+  end
+end

data/lib/geocodio/school_district.rb

@@ -0,0 +1,15 @@
+module Geocodio
+  class SchoolDistrict
+    attr_reader :name
+    attr_reader :lea_code
+    attr_reader :grade_low
+    attr_reader :grade_high
+
+    def initialize(payload = {})
+      @name       = payload['name']
+      @lea_code   = payload['lea_code']
+      @grade_low  = payload['grade_low']
+      @grade_high = payload['grade_high']
+    end
+  end
+end

data/lib/geocodio/state_legislative_district.rb

@@ -0,0 +1,16 @@
+module Geocodio
+  class StateLegislativeDistrict
+    attr_accessor :name
+    attr_accessor :district_number
+    attr_accessor :proportion
+    attr_accessor :ocd_id
+
+    def initialize(payload = {})
+      @name            = payload['name']
+      @district_number = payload['district_number'].to_i
+      @district_number = payload['district_number'] if @district_number == 0
+      @proportion      = payload['proportion']
+      @ocd_id          = payload['ocd_id']
+    end
+  end
+end

data/lib/geocodio/timezone.rb

@@ -0,0 +1,16 @@
+module Geocodio
+  class Timezone
+    attr_reader :name
+    attr_reader :utc_offset
+
+    def initialize(payload = {})
+      @name         = payload['name']
+      @utc_offset   = payload['utc_offset']
+      @observes_dst = payload['observes_dst']
+    end
+
+    def observes_dst?
+      !!@observes_dst
+    end
+  end
+end

data/lib/geocodio/utils.rb

@@ -0,0 +1,43 @@
+module Geocodio
+  module Utils
+    def parse_results(response)
+      results   = response.body['results']
+      input     = response.body['input']['formatted_address'] if response.body['input']
+      [results.map { |result| Address.new(result) }, input]
+    end
+
+    def parse_nested_results(response)
+      results = response.body['results']
+
+      results = results.map do |result_set|
+        addresses = Array(result_set['response']['results'])
+        addresses.map! { |result| Address.new(result) }
+
+        query = result_set['query']
+        input = result_set['response']['input']['formatted_address'] if result_set['response']['input']
+
+        AddressSet.new(query, *addresses, input: input)
+      end
+    end
+
+    def normalize_coordinates(coordinates)
+      return coordinates unless coordinates.is_a?(Hash)
+      coordinates.sort.map { |p| p[1] }.join(',')
+    end
+
+    def normalize_params_and_options(hash)
+      hash = Hash[hash.map { |k, v| [k.to_sym, v] }]
+
+      # The only supported parameter is fields
+      params = hash.select { |k, _| [:fields].include?(k) }
+
+      # Normalize this particular parameter to be a comma-separated string
+      params[:fields] = params[:fields].join(',') if params[:fields]
+
+      # The only supported option is `timeout`
+      options = hash.select { |k, _| [:timeout].include?(k) }
+
+      [params, options]
+    end
+  end
+end

data/lib/geocodio/version.rb

@@ -0,0 +1,13 @@
+module Geocodio
+  class Version
+    MAJOR = 1
+    MINOR = 7
+    PATCH = 0
+
+    def self.to_s
+      [MAJOR, MINOR, PATCH].join('.')
+    end
+  end
+
+  VERSION = Version.to_s
+end

data/lib/geocodio.rb

@@ -0,0 +1,9 @@
+require 'geocodio/address'
+require 'geocodio/address_set'
+require 'geocodio/client'
+require 'geocodio/canadian'
+
+require 'geocodio/version'
+
+module Geocodio
+end