rboc 1.0.0

data/lib/rboc/data.rb

@@ -0,0 +1,77 @@
+require 'json'
+
+module Census
+
+  # A result data set
+  #
+  class Data
+
+    # Split a list of column names into geographic columns and data columns
+    def self.split_colnames(colnames)
+      geocolnames = []
+      datacolnames = []
+      colnames.each do |s|
+        if Geography::LEVELS.include? s
+          geocolnames << s
+        else
+          datacolnames << s
+        end
+      end
+
+      [geocolnames, datacolnames]
+    end
+
+    include Enumerable
+
+    attr_reader :colnames, :rows
+
+    # Constructs a new data object from Census data returned by the API. The format of JSON
+    # should be:
+    #     [["column1", "column2", ...], [row11, row12, ...], [row21, row22, ...], ...]
+    #
+    def initialize(json='[]')
+      json = JSON.parse json if json.is_a? String
+      @colnames, *@rows = *json
+      @colmap = Hash[@colnames.zip (0..@colnames.length)]
+
+      @geocolnames, @datacolnames = self.class.split_colnames colnames
+    end
+
+    def each
+      @rows.each do |row|
+        yield Hash[@colnames.zip row]
+      end
+    end
+
+    # Merges an existing Census data set with additional data returned from the API. Currently,
+    # this method assumes columns and rows are returned in a consistent order given the same
+    # geography.
+    #
+    def merge!(json)
+      json = JSON.parse json if json.is_a? String
+      colnames, *rows = *json
+      colmap = Hash[colnames.zip (0..colnames.length)]
+      geocolnames, datacolnames = self.class.split_colnames colnames
+
+      if geocolnames != @geocolnames
+        raise ArgumentError, "Mismatched geographies"
+      end
+
+      @rows.map!.with_index do |row, i|
+        if  @geocolnames.any? {|s| row[@colmap[s]] != rows[i][colmap[s]]}
+          raise ArgumentError, "Mismatched rows"
+        end
+
+        row += datacolnames.map {|s| rows[i][colmap[s]]}
+      end
+
+      n = @colnames.length
+      @colmap.merge! Hash[datacolnames.zip (n..(n+datacolnames.length))]
+      @colnames += datacolnames
+      @datacolnames += datacolnames
+
+      self
+    end
+
+  end
+end

data/lib/rboc/geo.rb

@@ -0,0 +1,61 @@
+module Census
+
+  # A Census geography
+  #
+  class Geography
+    LEVELS = [
+      'us', 'region', 'division', 'state', 'county', 'tract'
+    ]
+
+    LEVEL_ALIAS = {
+      'regions' => 'region',
+      'divisions' => 'division',
+      'states' => 'state',
+      'counties' => 'county',
+      'tracts' => 'tract',
+    }
+
+    attr_accessor :summary_level, :contained_in
+
+    def initialize
+      @summary_level = {}
+      @contained_in = {}
+    end
+
+    # Sets the summary level to the specified value. If 'lvl' is a hash, it should
+    # only contain one element.
+    #
+    def summary_level=(lvl)
+
+      if lvl.is_a? Hash
+        k, v = lvl.first
+        k = LEVEL_ALIAS[k] if LEVEL_ALIAS[k] 
+        @summary_level[k] = v
+      else
+        k = LEVEL_ALIAS[lvl] || lvl
+        @summary_level[k] = '*'
+      end
+    end
+
+    def to_hash
+      h = {}
+      @summary_level['us'] = '*' if @summary_level.empty?
+
+      k, v = @summary_level.first
+      h['for'] = "#{k}:#{v}"
+
+      unless @contained_in.empty?
+        h['in'] = @contained_in.map {|k, v| "#{k}:#{v}"}.join("+")
+      end
+
+      h
+    end
+
+    # Returns the geography portion of the API GET string.
+    #
+    def to_s
+      URI.encode_www_form self.to_hash
+    end
+  end
+
+end

data/lib/rboc.rb

@@ -0,0 +1,226 @@
+require 'curb'
+require 'json'
+require 'uri'
+
+require 'rboc/geo'
+require 'rboc/data'
+
+# A module defining methods for accessing the U.S. Census data API.
+#
+module Census
+
+  # Base URL of the Census data API.
+  #
+  API_URL = 'http://api.census.gov/data'
+
+  # Path to the installed API key relative to this file.
+  #
+  INSTALLED_KEY_REL_PATH = '../data/installed_key'
+
+  # Path to the installed API key.
+  #
+  INSTALLED_KEY_PATH = File.join(File.dirname(File.expand_path(__FILE__)), INSTALLED_KEY_REL_PATH)
+
+  # Data files accessible through the Census API.
+  #
+  FILES = ['acs1', 'acs1_cd', 'acs3', 'acs5', 'sf1', 'sf3']
+
+  # List valid years of data for each data file.
+  #
+  FILE_VALID_YEARS = {
+    'acs1'    => [2012],
+    'acs1_cd' => [2011],
+    'acs3'    => [2012],
+    'acs5'    => [2011, 2010],
+    'sf1'     => [2010, 2000, 1990],
+    'sf3'     => [2000, 1990]
+  }
+
+  FILE_URL_SUBST = {
+    'acs1' => 'acs1/profile',
+    'acs3' => 'acs3/profile'
+  }
+
+  class CensusApiError < StandardError; end
+  class InvalidQueryError < CensusApiError; end
+  class InvalidKeyError < CensusApiError; end
+  class NoMatchingRecordsError < CensusApiError; end
+  class ServerSideError < CensusApiError; end
+
+  # A class representing a query to the Census API.
+  #
+  class Query
+    attr_accessor :variables, :geo
+
+    def initialize
+      @variables = []
+      @geo = Geography.new
+    end
+
+    def api_key=(key)
+      @api_key = key
+    end
+
+    # Returns the API key to be used for this query. If the key hasn't been set explicitly, this
+    # method attempts to load a key previously installed by Census#install_key!.
+    #
+    def api_key
+      @api_key ||= Census.installed_key
+    end
+
+    # these chainable methods mirror the field names in the HTTP get string
+
+    def get(*vars)
+      @variables = vars
+      self
+    end
+
+    def for(level)
+      @geo.summary_level = level
+      self
+    end
+
+    def in(container)
+      @geo.contained_in = container
+      self
+    end
+
+    def key(key)
+      @api_key = key
+      self
+    end
+
+    # Constructs a new Query object with a subset of variables. Creates a shallow copy of this
+    # Query's geography and api key.
+    #
+    def [](rng)
+      variables = @variables[rng]
+      q = Query.new
+      q.variables = variables
+      q.geo = @geo
+      q.api_key = @api_key
+      q
+    end
+
+    def to_hash
+      h = {}
+      h['key'] = self.api_key
+      h.merge! geo.to_hash
+
+      v = @variables
+      v = v.join(',') if v.is_a? Array
+      h['get'] = v
+
+      h
+    end
+
+    # Returns the query portion of the API GET string.
+    #
+    def to_s
+      URI.encode_www_form self.to_hash
+    end
+  end
+
+  class <<self
+
+    # Writes the given key to a local file. If a key is installed, then you don't have to specify
+    # a key in your query.
+    #
+    def install_key!(key)
+      File.open INSTALLED_KEY_PATH, 'w' do |f|
+        f.write key
+      end
+    end
+
+    def installed_key
+      if File.exists? INSTALLED_KEY_PATH
+        File.read INSTALLED_KEY_PATH
+      else
+        nil
+      end
+    end
+
+    # Constructs the URL needed to perform the query on the given file.
+    #
+    def api_url(year, file, url_file, query)
+      year = year.to_i
+      unless FILE_VALID_YEARS[file].include? year
+        raise ArgumentError, "Invalid year '#{year}' for file '#{file}'"
+      end
+
+      url_file ||= file
+      yield query if block_given?
+      [API_URL, year.to_s,  "#{url_file}?#{query.to_s}"].join('/')
+    end
+
+    # Accesses the data api and returns the unmodified body of the HTTP response.  Raises errors
+    # if the HTTP response code indicates a problem.
+    #
+    def api_raw(year, file, url_file, query)
+      yield query if block_given?
+      url = api_url year, file, url_file, query
+      puts "GET #{url}"
+
+      c = Curl::Easy.new url
+      c.perform
+      r = c.response_code
+
+      if r == 200
+        return c.body_str
+      elsif r == 400
+        raise InvalidQueryError
+      elsif r == 204
+        raise NoMatchingRecordsError
+      elsif r == 500
+        raise ServerSideError
+      elsif r == 302 && (c.head.include?("missing_key") || c.head.include?("invalid_key"))
+        raise InvalidKeyError
+      else
+        raise CensusApiError, "Unexpected HTTP response code: #{r}"
+      end
+    end
+
+    # Accesses the the data api and parses the result into a Census::Data object.
+    #
+    def api_data(year, file, url_file, query)
+      yield query if block_given?
+
+      # download the first 50 or fewer variables
+      json = api_raw year, file, url_file, query[0...50]
+      d = Data.new json
+
+      # download remaining variables 50 at a time
+      offset = 50
+      while offset <= query.variables.length
+        json = api_raw year, file, url_file, query[offset...(offset+50)]
+        json = JSON.parse json
+
+        # sometimes the API returns a descriptive hash (in a single element array) if the
+        # requested columns are invalid
+        raise InvalidQueryError if json.first.is_a? Hash
+
+        d.merge! json
+        offset += 50
+      end
+
+      d
+    end
+
+  end
+
+  def self.api_call(file, url_file)
+
+    define_singleton_method file do |year: FILE_VALID_YEARS[file].first, query: Query.new, &block|
+      api_data year, file, url_file, query, &block
+    end
+
+    define_singleton_method(file+'_raw') do |year: FILE_VALID_YEARS[file].first, query: Query.new, &block|
+      api_raw year, file, url_file, query, &block
+    end
+  end
+
+  FILES.each do |f| 
+    self.api_call f, FILE_URL_SUBST[f]
+  end
+
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: rboc
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Joshua Tokle
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: curb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.5
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.1
+description: An interface to the API provided by the U.S. Census Bureau
+email: jtokle@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/rboc.rb
+- lib/rboc/geo.rb
+- lib/rboc/data.rb
+- data/acs_1yr_profile_2012.xml
+homepage: http://github.com/jotok/rboc
+licenses:
+- Public Domain
+metadata: {}
+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.0.14
+signing_key: 
+specification_version: 4
+summary: An interface to the API provided by the U.S. Census Bureau
+test_files: []