policymap_wrap 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Gemini SBS, LLC
+
+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.rdoc

@@ -0,0 +1,154 @@
+= PolicyMap Wrap
+
+Ruby wrapper around the PolicyMap API.
+
+== Notes
+ 
+PolicyMap APIs are custom designed, so your mileage may vary depending on your API.
+
+== Usage
+
+Before you can perform searches, you must first setup your PolicyMap credentials:
+
+  PolicyMap::Client.set_credentials(<account_id>)
+  
+There are three types of searches: query, boundary and indicator.
+Each search is performed as follows, respectively:
+
+  PolicyMap::Client.query_search(<search_options>)
+  PolicyMap::Client.boundary_search(<search_options>)
+  PolicyMap::Client.indicator_search(<search_options>)
+  
+The search options (required and optional) will vary based on the type of search you are performing.
+
+=== PolicyMap::Client.query_search(<search_options>)
+
+A +:search+ type of search is a free form query that *returns an array of hashes (with symbolized keys)* each containing the 
+boundary id of each match.
+
+Required search options:
+
+  :query => "some sort of search string (eg, a city name: 'miami')"
+  :boundary_types => [:city, :zip]   # Array or single boundary type
+  
+Required search options for *some* boundary types:
+  
+  :state => "CA"   # state abbreviation
+  :county => "Miami Dade"
+  :census_tract => 35525   # Numeric representing a census tract
+  
+Optional search options:
+
+  :max => 25   # Max number of results in the resultset
+
+=== PolicyMap::Client.boundary_search(<search_options>)
+
+A +:boundary+ search *returns a hash (with symbolized keys)* containing a MultiPolygon.
+
+Required search options:
+
+  :boundary_types => [:city, :zip, :state]   # Can only specify 0 or 1 boundary type 
+                                             # if boundary IDs (below) are also specified
+  
+Other search options:
+
+  :boundary_ids => [1024944, 1024989]   # Array of boundary IDs
+  :lat => 33.805094   # Only to be used if boundary_ids (above) is not specified
+  :lng => -118.353717
+
+=== PolicyMap::Client.indicator_search(<search_options>)
+
+An +:indicator+ type of search *returns a hash (with symbolized keys)* containing indicator data for the specified boundaries.
+  
+Required search options:
+
+  :boundary_types => [:city, :zip, :state]   # Can only specify 0 or 1 boundary type 
+                                             # if boundary IDs (below) are also specified
+  :indicators => [:total_population, :percent_asian]
+  
+Other search options:
+
+  :boundary_ids => [1024944, 1024989]   # Array of boundary IDs
+  :lat => 33.805094   # Only to be used if boundary_ids (above) is not specified
+  :lng => -118.353717
+
+=== Available Boundary Types
+
+  :state
+  :county
+  :city
+  :zip
+  :census_tract 
+  :block_group
+  :congressional_district
+  :assembly_district
+  :senate_district
+  :all   # includes all boundary types
+
+=== Available Indicators
+
+Population
+
+  :total_population
+  :percent_african_american
+  :percent_asian
+  :percent_pacific_islander
+  :percent_hispanic
+  :percent_native_american
+  :percent_mixed_race
+  :percent_under_18
+  :percent_65_or_older
+  :percent_foreign_born
+  :percent_disabled
+  
+Education
+
+  :percent_high_school_or_less
+  :percent_college_degree
+  :percent_graduate_degree
+  
+Housing
+  
+  :median_home_value
+  :median_rent
+  :percent_moved_in_since_1990
+  :percent_homeowners
+  :vacancy_rate
+  
+Income
+
+  :median_household_income
+  :poverty_rate
+  :percent_households_wo_car
+  :average_vehicles_per_household
+  :percent_who_commute_to_work_using_public_transit
+  :unemployment_rate
+  
+Industry Concentrations
+  
+  :independent_artists
+  :performing_arts_and_spectator_sports
+  :movie_and_sound_industries
+  :mueseums_and_historical_sites
+  :publishing_industries
+  :broadcasting
+  :other_info_services
+  
+Other
+
+  :all   # includes all indicators
+
+== Dependencies
+
+PolicyMap Wrap stands on the shoulders of giants:
+
+* {yajl-ruby}[http://github.com/brianmario/yajl-ruby] (Ruby wrapper around the great {yajl}[http://lloyd.github.com/yajl])
+* {curb}[http://github.com/taf2/curb] (Ruby wrapper around the great {libcurl}[http://curl.haxx.se/])
+
+== Copyright
+
+Copyright (c) 2010 Gemini SBS. See LICENSE for details.
+
+== Authors
+
+* {Mauricio Gomes}[http://github.com/mgomes]

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/policymap.rb

@@ -0,0 +1,2 @@
+# So you can require "policymap" instead of "policymap_wrap"
+require "policymap_wrap"

data/lib/policymap_wrap.rb

@@ -0,0 +1,22 @@
+require 'uri'
+require 'yajl/json_gem'
+require 'curb'
+
+require 'policymap_wrap/connection'
+require 'policymap_wrap/endpoint'
+require 'policymap_wrap/hash_utils'
+require 'policymap_wrap/client'
+
+module PolicyMap
+  REALM = "http://staging.www.policymap.com"
+  VERSION = File.read(File.join(File.dirname(__FILE__), '..', 'VERSION'))
+  
+  class PolicyMapError < StandardError; end
+  class InsufficientArgsForSearch < PolicyMapError; end
+  class Unauthorized < PolicyMapError; end
+  class NotFound < PolicyMapError; end
+  class ServerError < PolicyMapError; end
+  class Unavailable < PolicyMapError; end
+  class DecodeError < PolicyMapError; end
+  class NoConnectionEstablished < PolicyMapError; end
+end

data/lib/policymap_wrap/client.rb

@@ -0,0 +1,126 @@
+module PolicyMap
+
+  class Client
+  
+    BOUNDARY_TYPES = { :state => 2, :county => 4, :city => 16, :zip => 8, :census_tract => 6, 
+                       :block_group => 15, :congressional_district => 23, :assembly_district => 48, 
+                       :senate_district => 49, :all => 'all' }
+                       
+    INDICATORS = { :total_population => 9840661, :percent_african_american => 9840139, :percent_asian => 9840102, 
+                   :percent_pacific_islander => 9840497, :percent_hispanic => 9840238, :percent_native_american => 9840708,
+                   :percent_mixed_race => 9840447, :percent_under_18 => 9840423, :percent_65_or_older => 9840365,
+                   :percent_foreign_born => 9840645, :percent_disabled => 9840630, :percent_high_school_or_less => 9840299,
+                   :percent_college_degree => 9840342, :percent_graduate_degree => 9840503, :median_home_value => 9840587,
+                   :median_rent => 9840655, :percent_moved_in_since_1990 => 9840118, :percent_homeowners => 9840172,
+                   :vacancy_rate => 9840676, :median_household_income => 9840169, :poverty_rate => 9840120,
+                   :percent_households_wo_car => 0, :average_vehicles_per_household => 9845668,
+                   :percent_who_commute_to_work_using_public_transit => 9845660, :unemployment_rate => 9841103,
+                   :independent_artists => 9618303, :performing_arts_and_spectator_sports => 9584608, 
+                   :movie_and_sound_industries => 9584731, :mueseums_and_historical_sites => 9584676,
+                   :publishing_industries => 9584638, :broadcasting => 9584691, :other_info_services => 9584624, :all => 'all' }
+    
+    @@connection = nil
+    @@debug = false
+    @@default_options = nil
+
+    class << self
+
+      def set_credentials(client_id)
+        @@default_options = { :id => client_id, :ty => 'data', :f => 'j' }
+        @@connection = Connection.new(client_id)
+        @@connection.debug = @@debug
+        true
+      end
+
+      def debug=(debug_flag)
+        @@debug = debug_flag
+        @@connection.debug = @@debug if @@connection
+      end
+
+      def debug
+        @@debug
+      end
+
+      def query_search(*args)
+        default_options = @@default_options
+        default_options[:t] = "sch"
+        
+        options = extract_options!(args)
+        
+        raise InsufficientArgsForSearch unless options.has_key?(:boundary_types) && options.has_key?(:query)
+        
+        options[:boundary_types] = Array(options[:boundary_types]).collect {|bt| BOUNDARY_TYPES[bt] }.join(',')
+        HashUtils.rename_key!(options, :boundary_types, :bt)
+        HashUtils.rename_key!(options, :query, :s)
+        HashUtils.rename_key!(options, :state, :st) if options.has_key?(:state)
+        HashUtils.rename_key!(options, :county, :co) if options.has_key?(:county)
+        HashUtils.rename_key!(options, :census_tract, :ct) if options.has_key?(:census_tract)
+        
+        options = default_options.merge(options)
+        
+        result = get(Endpoint.endpoint_url, options)
+        result['sch'].collect {|hsh| HashUtils.symbolize_keys(hsh) }
+      end
+      
+      def boundary_search(*args)
+        default_options = @@default_options
+        default_options[:t] = "bnd"
+        
+        options = extract_options!(args)
+        
+        raise InsufficientArgsForSearch unless options.has_key?(:boundary_types) || options.has_key?(:boundary_ids)
+        
+        options[:boundary_types] = Array(options[:boundary_types]).collect {|bt| BOUNDARY_TYPES[bt] }.join(',') if options.has_key?(:boundary_types)
+        options[:boundary_ids] = Array(options[:boundary_ids]).join(',') if options.has_key?(:boundary_ids)
+        HashUtils.rename_key!(options, :boundary_types, :bt) if options.has_key?(:boundary_types)
+        HashUtils.rename_key!(options, :boundary_ids, :bi) if options.has_key?(:boundary_ids)
+        HashUtils.rename_key!(options, :lng, :lon) if options.has_key?(:lng)
+        
+        options = default_options.merge(options)
+        
+        result = get(Endpoint.endpoint_url, options)
+        HashUtils.recursively_symbolize_keys(result["bnd"])
+      end
+      
+      def indicator_search(*args)
+        default_options = @@default_options
+        default_options[:t] = "ind"
+        
+        options = extract_options!(args)
+        
+        raise InsufficientArgsForSearch unless options.has_key?(:indicators) && (options.has_key?(:boundary_types) || options.has_key?(:boundary_ids))
+        
+        options[:indicators] = Array(options[:indicators]).collect {|i| INDICATORS[i] }.join(',')
+        options[:boundary_types] = Array(options[:boundary_types]).collect {|bt| BOUNDARY_TYPES[bt] }.join(',') if options.has_key?(:boundary_types)
+        options[:boundary_ids] = Array(options[:boundary_ids]).join(',') if options.has_key?(:boundary_ids)
+        HashUtils.rename_key!(options, :indicators, :ii)
+        HashUtils.rename_key!(options, :boundary_types, :bt) if options.has_key?(:boundary_types)
+        HashUtils.rename_key!(options, :boundary_ids, :bi) if options.has_key?(:boundary_ids)
+        HashUtils.rename_key!(options, :lng, :lon) if options.has_key?(:lng)
+        
+        options = default_options.merge(options)
+        
+        result = get(Endpoint.endpoint_url, options)
+        HashUtils.recursively_symbolize_keys(result["ind"])
+      end
+
+      def get(endpoint, data=nil)
+        raise NoConnectionEstablished  if @@connection.nil?
+        @@connection.get endpoint, data
+      end
+      
+    private
+    
+      def extract_options!(args)
+        if args.last.is_a?(Hash)
+          return args.pop
+        else
+          return {}
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/policymap_wrap/connection.rb

@@ -0,0 +1,136 @@
+module PolicyMap
+  
+  class Connection
+
+    attr_accessor :debug
+    attr_reader :client_id
+
+    def initialize(client_id)
+      @client_id = client_id
+      @debug = false
+    end
+
+    def get(endpoint, data=nil)
+      request :get, endpoint, data
+    end
+    
+    class Response
+      
+      attr_reader :code, :header, :body, :message
+      
+      HTTP_RESPONSES = { '100' => 'Continue', '101' => 'SwitchProtocol', '200' => 'OK', '201' => 'Created', '202' => 'Accepted', '203' => 'NonAuthoritativeInformation', 
+                         '204' => 'NoContent', '205' => 'ResetContent', '206' => 'PartialContent', '300' => 'MultipleChoice', '301' => 'MovedPermanently', 
+                         '302' => 'Found', '303' => 'SeeOther', '304' => 'NotModified', '305' => 'UseProxy', '307' => 'TemporaryRedirect', '400' => 'BadRequest', 
+                         '401' => 'Unauthorized', '402' => 'PaymentRequired', '403' => 'Forbidden', '404' => 'NotFound', '405' => 'MethodNotAllowed', 
+                         '406' => 'NotAcceptable', '407' => 'ProxyAuthenticationRequired', '408' => 'RequestTimeOut', '409' => 'Conflict', '410' => 'Gone', 
+                         '411' => 'LengthRequired', '412' => 'PreconditionFailed', '413' => 'RequestEntityTooLarge', '414' => 'RequestURITooLong', 
+                         '415' => 'UnsupportedMediaType', '416' => 'RequestedRangeNotSatisfiable', '417' => 'ExpectationFailed', '500' => 'InternalServerError', 
+                         '501' => 'NotImplemented', '502' => 'BadGateway', '503' => 'ServiceUnavailable', '504' => 'GatewayTimeOut', '505' => 'VersionNotSupported' }
+      
+      def initialize(http_client)
+        @code = http_client.response_code
+        @header = http_client.header_str.is_a?(String) ? parse_headers(http_client.header_str) : http_client.header_str
+        @body = http_client.body_str
+        @message = HTTP_RESPONSES[@code.to_s]
+      end
+      
+    private
+    
+      def parse_headers(header_string)
+        header_lines = header_string.split($/)
+        header_lines.shift
+        header_lines.inject({}) do |hsh, line|
+          whole_enchillada, key, value = /^(.*?):\s*(.*)$/.match(line.chomp).to_a
+          hsh[key] = value unless whole_enchillada.nil?
+          hsh
+        end
+      end
+      
+    end
+
+  private
+
+    def request(method, endpoint, data)
+      headers = { 'User-Agent' => "PolicyMap Ruby Client v#{VERSION}" }
+
+      if [:get].include?(method) && !data.nil?
+        endpoint = endpoint + '?' + build_query(data)
+      end
+
+      if debug
+        puts "request: #{method.to_s.upcase} #{endpoint}"
+        puts "headers:"
+        headers.each do |key, value|
+          puts "#{key}=#{value}"
+        end
+      end
+
+      response = send_request(method, endpoint, headers)
+
+      if debug
+        puts "\nresponse: #{response.code}"
+        puts "headers:"
+        response.header.each do |key, value|
+          puts "#{key}=#{value}"
+        end
+        puts "body:"
+        puts response.body
+      end
+
+      raise_errors(response)
+
+      if response.body.empty?
+        content = nil
+      else
+        begin
+          content = JSON.parse(response.body)
+        rescue JSON::ParserError
+          raise DecodeError, "content: <#{response.body}>"
+        end
+      end
+
+      content
+    end
+
+    def build_query(data)
+      data = data.to_a if data.is_a?(Hash)
+      data.map do |key, value|
+        [key.to_s, URI.escape(value.to_s)].join('=')
+      end.join('&')
+    end
+    
+    def send_request(method, endpoint, headers)
+      if method == :get
+        @http_client = Curl::Easy.new(endpoint) do |c|
+          c.headers = headers
+        end
+      end
+      
+      @http_client.perform
+      
+      Response.new(@http_client)
+    end
+
+    def raise_errors(response)
+      response_description = "(#{response.code}): #{response.message}"
+      response_description += " - #{response.body}" unless response.body.empty?
+
+      case response.code.to_i
+        when 401
+          raise Unauthorized
+        when 404
+          raise NotFound
+        when 500
+          raise ServerError, "PolicyMap had an internal error. Please let them know. #{response_description}"
+        when 502..503
+          raise Unavailable, response_description
+        else
+          unless response.code.to_i == 200
+            raise PolicyMapError, response_description
+          end
+      end
+    end
+      
+  end
+  
+end

data/lib/policymap_wrap/endpoint.rb

@@ -0,0 +1,15 @@
+module PolicyMap
+
+  class Endpoint
+
+    class << self
+
+      def endpoint_url
+        [REALM, 's/'].join('/')
+      end
+      
+    end
+
+  end
+
+end

data/lib/policymap_wrap/hash_utils.rb

@@ -0,0 +1,33 @@
+module PolicyMap
+  
+  class HashUtils
+    
+    def self.rename_key!(hash, old_key, new_key)
+      hash[new_key] = hash.delete(old_key)
+      hash
+    end
+    
+    def self.symbolize_keys(hash)
+      hash.inject({}) do |options, (key, value)|
+        options[(key.to_sym rescue key) || key] = value
+        options
+      end
+    end
+
+    def self.recursively_symbolize_keys(object)
+      if object.is_a? Hash
+        symbolized_hash = symbolize_keys(object)
+        symbolized_hash.each do |key, value|
+          symbolized_hash[key] = recursively_symbolize_keys(value)
+        end
+        symbolized_hash
+      elsif object.is_a? Array
+        object.map {|value| recursively_symbolize_keys(value) }
+      else
+        object
+      end
+    end
+    
+  end
+  
+end

data/spec/policymap_wrap_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "PolicymapWrap" do
+  it "fails" do
+    fail "hey buddy, you should probably rename this file and start specing for real"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'policymap_wrap'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification 
+name: policymap_wrap
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Mauricio Gomes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-27 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: yajl-ruby
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 0
+        - 7
+        - 7
+        version: 0.7.7
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: curb
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 105
+        segments: 
+        - 0
+        - 7
+        - 7
+        - 1
+        version: 0.7.7.1
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id003
+description: Ruby wrapper around the PolicyMap API. Your API may vary.
+email: mauricio@geminisbs.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- VERSION
+- lib/policymap.rb
+- lib/policymap_wrap.rb
+- lib/policymap_wrap/client.rb
+- lib/policymap_wrap/connection.rb
+- lib/policymap_wrap/endpoint.rb
+- lib/policymap_wrap/hash_utils.rb
+- spec/policymap_wrap_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/geminisbs/policymap_wrap
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Ruby wrapper around the PolicyMap API
+test_files: 
+- spec/policymap_wrap_spec.rb
+- spec/spec_helper.rb