census_api 0.1.0

data/.gitignore

@@ -0,0 +1,22 @@
+.DS_Store
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+pkg/*
+rdoc
+spec/reports
+spec/vcr_cassettes
+spec/vcr_cassettes/*
+spec/api_key.rb
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 TODO: Write your name
+
+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.

data/README.md

@@ -0,0 +1,468 @@
+# Census API
+
+This gem provides a Ruby wrapper around the Census Bureau API.
+
+
+## Obtaining an API key
+
+To be able to use this gem, you'll need a Census Bureau API key. To request an API key, visit
+http://www.census.gov/developers/tos/key_request.html and follow the instructions.
+
+
+## Installing the gem
+
+To use this gem, install it with <tt>gem install census_api</tt> or add it to your Gemfile:
+
+`gem 'cemsus_api'`
+
+And install it with <tt>bundle install</tt>
+
+## Usage
+
+### Retrieving Census Data
+
+First register a new Client:
+
+`@client = CensusApi::Client.new(API_KEY)`
+
+To query the 2010 Census SF1 dataset:
+
+`@client.sf1(fields, for, in*)`
+
+To query the 2006-2010 ACS5 dataset:
+
+`@client.acs5(fields, for, in*)`
+
+For a list of the fields available for each dataset, review the reference PDFs linked at the bottom of this document.
+
+#### Parameters
+
+The 'fields' parameter is a comma separated string of SF1 field names.
+
+The 'for' parameter is a single geography type, and optionally, the geography ids (geoid) for specific geographies of that type. A colon separates the geography type from the id and a comma separates ids.
+
+For example, 'STATE:06,02' would reference the state of California and Alaska.
+
+The 'in' parameter is a set of geography types or geography. Similar to the 'for' parameter, a colon separates the geography type from the id and a comma separates ids. Sets of geography are separated by a plus symbol.
+
+For example, 'STATE:02+COUNTY:290' would reference the 'Yukon-Koyukuk Census Area' County in the state of Alaska.
+
+The 'in' parameter is optional, or required, depending upon the geography type. The smaller the geography type being required, the more the request must be restricted by the 'in' parameter.
+
+## Census 2010 SF1 Examples and Supported Geography
+
+#### STATE - *(040) state*
+
+Retrieve fields for all States:
+
+`@client.sf1('P0010001', 'STATE')`
+
+Retrieve fields for California (geoid: 06):
+
+`@client.sf1('P0010001', 'STATE:06')`
+
+Retrieve fields for California and Alaska:
+
+`@client.sf1('P0010001', 'STATE:06,02')`
+
+#### COUNTY - *(050) state-county*
+
+Retrieve fields for all Counties:
+
+`@client.sf1('P0010001', 'COUNTY')`
+
+Retrieve fields for Counties in California:
+
+`@client.sf1('P0010001', 'COUNTY', 'STATE:06')`
+
+Retrieve fields for a specific County in California:
+
+`@client.sf1('P0010001', 'COUNTY:001', 'STATE:06')`
+
+#### COUSUB - *(060) state-county-county subdivision*
+
+Retrieve fields for all County Subdivisions within a specific County:
+
+`@client.sf1('P0010001', 'COUSUB', 'STATE:02+COUNTY:290')`
+
+Retrieve fields for a specific County Subdivision within a specific County:
+
+`@client.sf1('P0010001', 'COUSUB:86690', 'STATE:02+COUNTY:290')`
+
+Note: You must also specify the State the County belongs to.
+
+#### SUBMCD - *(067) state-county-county subdivision-subminor civil subdivision*
+
+Retrieve fields for all Subminor Civil Subdivisions within a specific County Subdivision:
+
+`@client.sf1('P0010001', 'SUBMCD', 'STATE:72+COUNTY:127+COUSUB:79693')`
+
+Retrieve fields for a specific Subminor Civil Subdivisions within a specific County Subdivision:
+
+`@client.sf1('P0010001', 'SUBMCD:02350', 'STATE:72+COUNTY:127+COUSUB:79693')`
+
+#### TABBLOCK - *(101) state-county-tract-block*
+
+Retrieve fields for all Blocks within a specific Tract
+
+`@client.sf1('P0010001', 'TABBLOCK', 'STATE:02+COUNTY:290+TRACT:00100')`
+
+Retrieve fields for a specific Subminor Civil Subdivisions within a specific County Subdivision:
+
+`@client.sf1('P0010001', 'SUBMCD:02350', 'STATE:72+COUNTY:127+COUSUB:79693')`
+
+#### TRACT - *(140) state-county-tract*
+
+Retrieve fields for all Tracts within a specific County:
+
+`@client.sf1('P0010001', 'TRACT', 'STATE:02+COUNTY:170')`
+
+Retrieve fields for a specific Tract within a specific County:
+
+`@client.sf1('P0010001', 'TRACT:000101', 'STATE:02+COUNTY:170')`
+
+#### BG - *(150) state-county- tract-block group*
+
+Retrieve fields for all Block Groups within a specific Tract:
+
+`@client.sf1('P0010001', 'BG', 'STATE:02+COUNTY:170+TRACT:000101')`
+
+Retrieve fields for a specific Block Group within a specific Tract:
+
+`@client.sf1('P0010001', 'BG:1', 'STATE:02+COUNTY:170+TRACT:000101')`
+
+#### PLACE -*(160) state-place*
+
+Retrieve fields for all Places:
+
+`@client.sf1('P0010001', 'PLACE')`
+
+Retrieve fields for all Places within a specific State:
+
+`@client.sf1('P0010001', 'PLACE', 'STATE:06')`
+
+Retrieve fields for a specific place within a specific State:
+
+`@client.sf1('P0010001', 'PLACE:00135', 'STATE:06')`
+
+#### ANRC - *(260) state-alaska native regional corporation*
+
+Retrieve fields for all Alaska Native Regional Corporations:
+
+`@client.sf1('P0010001', 'ANRC')`
+
+Retrieve fields for all Alaska Native Regional Corporations within a specific State:
+
+`@client.sf1('P0010001', 'ANRC', 'STATE:02')`
+
+Retrieve fields for all Alaska Native Regional Corporations within a specific State:
+
+`@client.sf1('P0010001', 'ANRC:00590', 'STATE:02')`
+
+#### AIANNH - *(280) state-american indian area/alaska native area/hawaiian home land*
+
+Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Land:
+
+`@client.sf1('P0010001', 'AIANNH')`
+
+Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Land within a specific State:
+
+`@client.sf1('P0010001', 'AIANNH', 'STATE:02')`
+
+Retrieve fields for a specific American Indian Area/Alaska Native Area/Hawaiian Home Land within a specific State:
+
+`@client.sf1('P0010001', 'AIANNH:03800', 'STATE:02')`
+
+#### AITS - *(281) state-american indian area-tribal subdivision*
+
+Retrieve fields for all American Indian Area-Tribal Subdivisions:
+
+`@client.sf1('P0010001', 'AITS')`
+
+Retrieve fields for all American Indian Area-Tribal Subdivisions in a specific American Indian Area:
+
+`@client.sf1('P0010001', 'AITS', 'STATE:40+AIANNH:13735')`
+
+Retrieve fields for a specific American Indian Area-Tribal Subdivision in a specific American Indian Area:
+
+`@client.sf1('P0010001', 'AITS:83127', 'STATE:40+AIANNH:13735')`
+
+#### CBSA - *(320) state-metropolitan statistical area/micropolitan statistical area*
+
+Retrieve fields from all Metropolitan Statistical Areas / Micropolitan Statistical Areas in a specific State:
+
+`@client.sf1('P0010001', 'CBSA', 'STATE:02')`
+
+Retrieve fields from a specific Metropolitan Statistical Areas / Micropolitan Statistical Areas in a specific State:
+
+`@client.sf1('P0010001', 'CBSA:11260', 'STATE:02')`
+
+#### METDIV - *(323)  state-metropolitan statistical area/micropolitan statistical area- metropolitan division*
+
+Retrieve fields from all Metropolitan Divisions in a specific Metropolitan Statistical Area / Micropolitan Statistical Area:
+
+`@client.sf1('P0010001', 'METDIV', 'STATE:06+CBSA:31100')`
+
+Retrieve fields from all Metropolitan Division in a specific Metropolitan Statistical Area / Micropolitan Statistical Area:
+
+`@client.sf1('P0010001', 'METDIV', 'STATE:06+CBSA:31100')`
+
+Retrieve fields from a specific Metropolitan Division in a specific Metropolitan Statistical Area / Micropolitan Statistical Area:
+
+`@client.sf1('P0010001', 'METDIV:31084', 'STATE:06+CBSA:31100')`
+
+#### CSA - *(340) - state-combined statistical area*
+
+Retrieve fields from all Combined Statistical Areas in a specific State:
+
+`@client.sf1('P0010001', 'CSA', 'STATE:24')`
+
+Retrieve fields from a specific Combined Statistical Area in a specific State:
+
+`@client.sf1('P0010001', 'CSA:428', 'STATE:24')`
+
+#### CD - *(500) state-congressional district*
+
+Retrieve fields from all Congressional Districts in a specific State:
+
+`@client.sf1('P0010001', 'CD', 'STATE:24')`
+
+Retrieve fields from a specific Congressional District in a specific State:
+
+`@client.sf1('P0010001', 'CD:01', 'STATE:24')`
+
+#### COUNTY (Remainder) - *(510) state-congressional district-county*
+
+Retrieve fields for all Counties within a specific Congressional District:
+
+`@client.sf1('P0010001', 'COUNTY', 'STATE:24+CD:01')`
+
+Retrieve fields for a specific County within a specific Congressional District:
+
+`@client.sf1('P0010001', 'COUNTY:01', 'STATE:24+CD:01')`
+
+#### TRACT (Remainder) - *(511) state-congressional district-county-tract*
+
+Retrieve fields for all Tracts within a specific Congressional District, County Remainder:
+
+`@client.sf1('P0010001', 'TRACT', 'STATE:24+CD:01+COUNTY:003')`
+
+Retrieve fields for a specific County within a specific Congressional District, County Remainder:
+
+`@client.sf1('P0010001', 'TRACT:702100', 'STATE:24+CD:01+COUNTY:003')`
+
+### COUSUB (Remainder) - *(521) state-congressional district-county-county subdivision*
+
+Retrieve fields for all County Subdivisions within a specific Congressional District, County Remainder:
+
+`@client.sf1('P0010001', 'COUSUB', 'STATE:24+CD:01+COUNTY:003')`
+
+Retrieve fields for a specific County Subdivision within a specific Congressional District, County Remainder:
+
+`@client.sf1('P0010001', 'COUSUB:90100', 'STATE:24+CD:01+COUNTY:003')`
+
+#### PLACE (Remainder) - *(531) state congressional district-place*
+
+Retrieve fields for all Places within a specific Congressional District:
+
+`@client.sf1('P0010001', 'PLACE', 'STATE:24+CD:01')`
+
+Retrieve fields for a specific Place within a specific Congressional District, County Remainder:
+
+`@client.sf1('P0010001', 'PLACE:00125', 'STATE:24+CD:01')`
+
+#### AIANNH (Remainder) - *550) state-congressional district-american indian area/alaska native area/hawaiian home land*
+
+Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Lands within a specific Congressional District:
+
+`@client.sf1('P0010001', 'AIANNH', 'STATE:02+CD:00')`
+
+Retrieve fields for a specific American Indian Area/Alaska Native Area/Hawaiian Home Land  within a specific Congressional District:
+
+`@client.sf1('P0010001', 'AIANNH:03800', 'STATE:02+CD:00')`
+
+#### ANRC (Remainder) - *(560) state-congressional district-alaska native regional corporation*
+
+Retrieve fields for all Alaska Native Regional Corporations within a specific Congressional District:
+
+`@client.sf1('P0010001', 'AIANNH', 'STATE:02+CD:00')`
+
+Retrieve fields for a specific Alaska Native Regional Corporation  within a specific Congressional District:
+
+`@client.sf1('P0010001', 'AIANNH:00590', 'STATE:02+CD:00')`
+
+#### SLDU - *(610) state-state legislative district (upper chamber)*
+
+Retrieve fields for all State Legislative Districts (Upper Chamber) within a State:
+
+`@client.sf1('P0010001', 'SLDU', 'STATE:02')`
+
+Retrieve fields for a specific State Legislative District (Upper Chamber) within a State:
+
+`@client.sf1('P0010001', 'SLDU:00A', 'STATE:02')`
+
+#### SLDU - *(620) state-state legislative district (upper chamber)*
+
+Retrieve fields for all State Legislative Districts (Lower Chamber) within a State:
+
+`@client.sf1('P0010001', 'SLDL', 'STATE:02')`
+
+Retrieve fields for a specific State Legislative District (Upper Chamber) within a State:
+
+`@client.sf1('P0010001', 'SLDL:001', 'STATE:02')`
+
+#### ZCTA5 - *(871) state-zip code tabulation area*
+
+Retrieve fields for all Zip Code Tabulation Areas within a specific State:
+
+`@client.sf1('P0010001', 'ZCTA', 'STATE:02')`
+
+Retrieve fields for a specific Zip Code Tabulation Area within a specific State:
+
+`@client.sf1('P0010001', 'ZCTA:99501', 'STATE:02')`
+
+## ACS5 2010 Examples and Supported Geography
+
+Querying the Census Bureau for ACS5 data is done in the same format as querying for census data.  The only difference is the geographies and fields available.
+
+#### STATE - *(040) state *
+
+Retrieve fields for all States:
+
+`@client.acs5('B00001_001E', 'STATE')`
+
+Retrieve fields for California (geoid: 06):
+
+`@client.acs5('B00001_001E', 'STATE:06')`
+
+Retrieve fields for California and Alaska:
+
+`@client.acs5('B00001_001E', 'STATE:06,02')`
+
+#### COUNTY - *(050) state-county*
+
+Retrieve fields for all Counties:
+
+`@client.acs5('B00001_001E', 'COUNTY')`
+
+Retrieve fields for Counties in California:
+
+`@client.acs5('B00001_001E', 'COUNTY', 'STATE:06')`
+
+Retrieve fields for a specific County in California:
+
+`@client.acs5('B00001_001E', 'COUNTY:001', 'STATE:06')`
+
+#### COUSUB - *(060) state-county-county subdivision*
+
+Retrieve fields for all County Subdivisions within a specific County:
+
+`@client.acs5('B00001_001E', 'COUSUB', 'STATE:02+COUNTY:290')`
+
+Retrieve fields for a specific County Subdivision within a specific County:
+
+`@client.acs5('B00001_001E', 'COUSUB:86690', 'STATE:02+COUNTY:290')`
+
+Note: You must also specify the State the County belongs to.
+
+#### SUBMCD - *(067) state-county-county subdivision-subminor civil subdivision*
+
+Retrieve fields for all Subminor Civil Subdivisions within a specific County Subdivision:
+
+`@client.acs5('B00001_001E', 'SUBMCD', 'STATE:72+COUNTY:127+COUSUB:79693')`
+
+Retrieve fields for a specific Subminor Civil Subdivision within a specific County Subdivision:
+
+`@client.acs5('B00001_001E', 'SUBMCD:02350', 'STATE:72+COUNTY:127+COUSUB:79693')`
+
+#### PLACE - *(070) state-county-county subdivision-place*
+
+Retrieve fields for all Places within a specific County Subdivision:
+
+`@client.acs5('B00001_001E', 'PLACE', 'STATE:02+COUNTY:290+COUSUB:86690')`
+
+Retrieve fields for a specific Place within a specific County Subdivision:
+
+`@client.acs5('B00001_001E', 'PLACE:05750', 'STATE:02+COUNTY:290+COUSUB:86690')`
+
+#### TRACT - *(080) state-county-county subdivision-place-tract*
+
+Retrieve fields for all Tracts within a specific Place:
+
+`@client.acs5('B00001_001E', 'TRACT', 'STATE:02+COUNTY:290+COUSUB:86690+PLACE:05750')`
+
+Retrieve fields for a specific Tract within a specific Place:
+
+`@client.acs5('B00001_001E', 'TRACT:000100', 'STATE:02+COUNTY:290+COUSUB:86690+PLACE:05750')`
+
+#### TRACT - *(140) state-county-tract*
+
+Retrieve fields for all Tracts within a specific County:
+
+`@client.acs5('B00001_001E', 'TRACT', 'STATE:02+COUNTY:170')`
+
+Retrieve fields for a specific Tract within a specific County:
+
+`@client.acs5('B00001_001E', 'TRACT:000101', 'STATE:02+COUNTY:170')`
+
+#### BG - *(150) state-county- tract-block group*
+
+Retrieve fields for all Block Groups within a specific Tract:
+
+`@client.acs5('B00001_001E', 'BG', 'STATE:02+COUNTY:170+TRACT:000101')`
+
+Retrieve fields for a specific Block Group within a specific Tract:
+
+`@client.acs5('B00001_001E', 'BG:1', 'STATE:02+COUNTY:170+TRACT:000101')`
+
+#### PLACE - *(160) state-place*
+
+Retrieve fields for all Places:
+
+`@client.acs5('B00001_001E', 'PLACE')`
+
+Retrieve fields for all Places within a specific State:
+
+`@client.acs5('B00001_001E', 'PLACE', 'STATE:06')`
+
+Retrieve fields for a specific place within a specific State:
+
+`@client.acs5('B00001_001E', 'PLACE:00135', 'STATE:06')`
+
+#### AIANNH - *(280) state-american indian area/alaska native area/hawaiian home land*
+
+Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Land:
+
+`@client.acs5('B00001_001E', 'AIANNH')`
+
+Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Land within a specific State:
+
+`@client.acs5('B00001_001E', 'AIANNH', 'STATE:02')`
+
+Retrieve fields for a specific American Indian Area/Alaska Native Area/Hawaiian Home Land within a specific State:
+
+`@client.acs5('B00001_001E', 'AIANNH:03800', 'STATE:02')`
+
+#### CD - *(500) state-congressional district*
+
+Retrieve fields from all Congressional Districts in a specific State:
+
+`@client.acs5('B00001_001E', 'CD', 'STATE:24')`
+
+Retrieve fields from a specific Congressional District in a specific State:
+
+`@client.acs5('B00001_001E', 'CD:01', 'STATE:24')`
+
+## Additional Resources
+
+For a list of all the fields available for the 2010 Census, please consult the following PDF:
+
+2010 Census Summary File 1 - Census Bureau
+
+http://www.census.gov/prod/cen2010/doc/sf1.pdf
+
+For a list of all the fields available for the 2006-2010 ACS5, please consult the following PDF:
+
+The 2006-2010 ACS 5-Year Summary File - Census Bureau
+
+http://www2.census.gov/acs2010_5yr/summaryfile/ACS_2006-2010_SF_Tech_Doc.pdf

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/census_api.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'census_api/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "census_api"
+  gem.version       = CensusApi::VERSION
+  gem.authors       = ["Ty Rauber"]
+  gem.email         = ["tyrauber@mac.com"]
+  gem.description   = %q{A Ruby Gem for querying the US Census Bureau API}
+  gem.summary       = %q{A Ruby Wrapper for the US Census Bureau API, providing the ability to query both the 2010 Census and 2006-2010 ACS5 datasets.}
+  gem.homepage      = "https://github.com/tyrauber/census_api.git"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  
+  gem.add_runtime_dependency "rest-client"
+  gem.add_runtime_dependency "hpricot"
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'fakeweb'
+  gem.add_development_dependency 'vcr'
+end

data/lib/census_api/client.rb

@@ -0,0 +1,19 @@
+module CensusApi
+  class Client
+    attr_reader :api_key
+    attr_reader :options
+
+    def initialize(api_key, options = {})
+      @api_key = api_key
+      @options = options
+    end
+
+    def sf1(field, level, *within)
+      Request.find("sf1", {:key => @api_key, :fields => field, :level => level, :within => within})
+    end
+    
+    def acs5(field, level, *within)
+      Request.find("acs5", {:key => @api_key, :fields => field, :level => level,  :within => within})
+    end
+  end
+end

data/lib/census_api/request.rb

@@ -0,0 +1,74 @@
+module CensusApi
+  class Request
+    
+    require 'restclient'
+    require 'hpricot'
+    require 'json'
+    require "yaml"
+    
+    attr_accessor :response
+    
+    @@census_shapes
+    
+    CENSUS_URL = "http://api.census.gov/data/2010"
+
+    def self.find(source, options = {})
+      flds = options[:fields].split(",").push("NAME").join(",")
+      params = { :key => options[:key], :get => flds, :for => format(options[:level],false) }
+      params.merge!({ :in => format(options[:within][0],true) }) if !options[:within].empty?
+      request = new(CENSUS_URL, source, params)
+      request.parse_response
+    end
+
+    def initialize(url, source, options)
+      path = "#{url}/#{source}?#{options.to_p}"
+      @response = RestClient.get(path){ 
+        |response, request, result, &block|
+          response
+      }
+      return @response
+    end
+    
+    def parse_response
+      case @response.code
+        when 200
+          response = JSON.parse(@response)
+          header = response.delete_at(0)
+          return response.map{|r| Hash[header.map{|h| h.gsub("NAME","name")}.zip(r)]}
+        else
+          return {:code => @response.code, :message=> "Invalid API key or request", :location=> @response.headers[:location]}
+        end
+    end
+    
+    protected
+  
+    def self.format(str,truncate)
+      result = str.split("+").map{|s|
+        if s.match(":")
+          s = s.split(":")
+        else 
+          s = [s,"*"]
+        end
+        shp = shapes[s[0].upcase]
+        s.shift && s.unshift(shp['name'].downcase.gsub(" ", "+")) if !shp.nil?
+        s.unshift(s.shift.split("/")[0]) if !s[0].scan("home+land").empty? && truncate
+        s.join(":")
+      }
+      return result.join("+")
+    end 
+    
+    def self.shapes
+      return  @@census_shapes if defined?( @@census_shapes)
+      @@census_shapes = {} 
+      YAML.load_file("lib/yml/census_shapes.yml").each{|k,v| @@census_shapes[k] = v}
+      return @@census_shapes
+    end
+    
+  end
+end
+
+class Hash
+   def to_p
+     self.map { |k,v| "#{k}=#{v}" }.join("&")
+   end
+end

data/lib/census_api/version.rb

@@ -0,0 +1,3 @@
+module CensusApi
+  VERSION = "0.1.0"
+end

data/lib/census_api.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+
+%w(version client request).each do |file|
+  require File.join(File.dirname(__FILE__), 'census_api', file)
+end

data/lib/yml/census_shapes.yml

@@ -0,0 +1,133 @@
+---
+STATE:
+  sumlevel: '040'
+  slug: STATE
+  name: State
+  description: state
+  path: STATE/2010
+COUNTY:
+  sumlevel: '050'
+  slug: COUNTY
+  name: County
+  description: state-county
+  path: COUNTY/2010
+COUSUB:
+  sumlevel: '060'
+  slug: COUSUB
+  name: County Subdivision
+  description: state-county-county subdivision
+  path: COUSUB/2010
+SUBMCD:
+  sumlevel: '067'
+  slug: SUBMCD
+  name: Subminor Civil Subdivision
+  description: state-county-county subdivision-subminor civil subdivision
+  path: SUBMCD/2010
+TABBLOCK:
+  sumlevel: '101'
+  slug: TABBLOCK
+  name: Block
+  description: state-county-tract-block
+  path: TABBLOCK/2010
+TRACT:
+  sumlevel: '140'
+  slug: TRACT
+  name: Tract
+  description: state-county-tract
+  path: TRACT/2010
+BG:
+  sumlevel: '150'
+  slug: BG
+  name: Block Group
+  description: state-county-tract-block group
+  path: BG/2010
+PLACE:
+  sumlevel: '160'
+  slug: PLACE
+  name: Place
+  description: state-place
+  path: PLACE/2010
+ANRC:
+  sumlevel: '230'
+  slug: ANRC
+  name: Alaska Native Regional Corporation
+  description: state-alaska native regional corporation
+  path: ANRC/2010
+AIANNH:
+  sumlevel: '280'
+  slug: AIANNH
+  name: American Indian Area/Alaska Native Area/Hawaiian Home Land
+  description: state-american indian area/alaska native area/hawaiian home land
+  path: AIANNH/2010
+AITS:
+  sumlevel: '281'
+  slug: AITS
+  name: Tribal Subdivision
+  description: state-american indian area-tribal subdivision
+  path: AITS/2010
+CBSA:
+  sumlevel: '320'
+  slug: CBSA
+  name: Metropolitan Statistical Area/Micropolitan Statistical Area
+  description: state-metropolitan statistical area/micropolitan statistical area
+  path: CBSA/2010
+METDIV:
+  sumlevel: '323'
+  slug: METDIV
+  name: Metropolitan Division
+  description: state-metropolitan statistical area/micropolitan statistical area-metropolitan division
+  path: METDIV/2010
+CSA:
+  sumlevel: '340'
+  slug: CSA
+  name: Combined Statistical Area
+  description: state-combined statistical area
+  path: CSA/2010
+CD:
+  sumlevel: '500'
+  slug: CD
+  name: Congressional District
+  description:	state-congressional district (111th)
+  path: CD/111
+SLDU:
+  sumlevel: '610'
+  slug: SLDU
+  name: State Legislative District (Upper Chamber)
+  description: state-state legislative district (upper chamber)
+  path: SLDU/2010
+SLDL:
+  sumlevel: '620'
+  slug: SLDL
+  name: State Legislative District (Lower Chamber)
+  description: state-state legislative district (lower chamber)
+  path: SLDL/2010
+VTD:
+  sumlevel: '700'
+  slug: VTD
+  name: Voting District
+  description: State-County-Voting District/Remainder
+  path: VTD/2010
+ZCTA5:
+  sumlevel: '871'
+  slug: ZCTA5
+  name: ZIP Code Tabulation Area
+  description: state-zip code tabulation area
+  path: ZCTA5/2010
+ELSD:
+  sumlevel: '950'
+  slug: ELSD
+  name: School District (Elementary)
+  description: State-School District (Elementary)/Remainder
+  path: ELSD/2010
+SCSD:
+  sumlevel: '960'
+  slug: SCSD
+  name: School District (Secondary)
+  description: State-School District (Secondary)/Remainder
+  path: SCSD/2010
+UNSD:
+  sumlevel: '970'
+  slug: UNSD
+  name: School District (Unified)
+  description: State-School District (Unified)/Remainder
+  path: UNSD/2010

data/spec/api_key.sample.rb

@@ -0,0 +1 @@
+RSPEC_API_KEY = 'abc123'

data/spec/census_api/client_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+describe CensusApi::Client do
+
+  it 'should not initialize without an api_key' do
+    lambda { CensusApi::Client.new }.should raise_error
+  end
+
+  it 'should initialize with an api_key' do
+    @client = CensusApi::Client.new(api_key)
+    @client.api_key.should == api_key
+  end
+
+  it 'should request sf1' do
+    source, options = 'sf1', {:key=> api_key, :fields => 'P0010001', :level => 'STATE:06', :within=>[]}
+    @client = CensusApi::Client.new(api_key)
+    CensusApi::Request.should_receive(:find).with(source, options)
+    @client.sf1(options[:fields], options[:level])
+  end
+
+  it 'should request acs5' do
+    source, options = 'acs5', {:key=> api_key, :fields => 'B00001_001E', :level => 'STATE:06', :within=>[]}
+    @client = CensusApi::Client.new(api_key)
+    CensusApi::Request.should_receive(:find).with(source, options)
+    @client.acs5(options[:fields], options[:level])
+  end
+  
+end

data/spec/census_api/request_spec.rb

@@ -0,0 +1,115 @@
+require 'spec_helper'
+
+describe CensusApi::Request do
+
+  context "#find" do
+    [{:source => 'sf1', :field => 'P0010001', :results=> [
+        {"P0010001"=>"37253956", "name"=>"California", "state"=>"06"},
+        {"P0010001"=>"1510271", "name"=>"Alameda County", "state"=>"06", "county"=>"001"}
+      ]},
+      {:source => 'acs5', :field => 'B00001_001E', :results =>[
+        {"B00001_001E"=>"2330290", "name"=>"California", "state"=>"06"},
+        {"B00001_001E"=>"92854", "name"=>"Alameda County", "state"=>"06", "county"=>"001"}
+      ]}
+    ].each do |test|
+    
+      describe "#{test[:source]} for a geography type" do
+        use_vcr_cassette "#{test[:source]}_find_states"
+
+        before(:each) do
+          params = {:key=> api_key, :fields => test[:field], :level => 'STATE', :within=>[]}
+          @collection = CensusApi::Request.find(test[:source], params)      
+        end
+
+        it 'should have 52 results' do
+          @collection.count.should == 52
+        end
+      
+        it 'should include fields for each result' do
+          @collection.each do |result|
+            result.should include(test[:field])
+            result.should include('name')
+            result.should include('state')
+          end
+        end
+      end
+    
+      describe "#{test[:source]} for a geography type and id" do
+        use_vcr_cassette "#{test[:source]}_find_state_with_id"
+
+        before(:each) do
+          params = {:key=> api_key, :fields => test[:field], :level => 'STATE:06', :within=>[]}
+          @collection = CensusApi::Request.find(test[:source], params)      
+        end
+
+        it 'should have one result' do
+          @collection.count.should == 1
+        end
+      
+        it 'should include fields for each result' do
+          @collection.each do |result|
+            result.should == test[:results][0]
+          end
+        end
+      end
+    
+      describe "#{test[:source]} for a geography type in a geography type" do
+         use_vcr_cassette "#{test[:source]}_find_counties_in_state"
+
+         before(:each) do
+           params = {:key=> api_key, :fields => test[:field], :level => 'COUNTY', :within=>['STATE:06']}
+           @collection = CensusApi::Request.find(test[:source], params)      
+         end
+
+         it 'should have one result' do
+           @collection.count.should == 58
+         end
+
+         it 'should include fields for each result' do
+           @collection.each do |result|
+             result.should include(test[:field])
+             result.should include('name')
+             result.should include('state')
+           end
+         end
+       end
+     
+       describe "#{test[:source]} for a geography type and id in a geography type" do
+          use_vcr_cassette "#{test[:source]}_find_county_in_state"
+
+           before(:each) do
+             params = {:key=> api_key, :fields => test[:field], :level => 'COUNTY:001', :within=>['STATE:06']}
+             @collection = CensusApi::Request.find(test[:source], params)      
+           end
+
+           it 'should have one result' do
+             @collection.count.should == 1
+           end
+
+           it 'should include fields for each result' do
+             @collection.each do |result|
+               result.should == test[:results][1]
+             end
+           end
+         end
+    end
+  end
+
+  context "#format" do
+    it 'should add wildcard after reformatting geography type without id' do
+      CensusApi::Request.format('COUSUB', false).should == 'county+subdivision:*'
+    end
+
+    it 'should maintain geography id after reformatting geography type' do
+      CensusApi::Request.format('COUSUB:86690', false).should == 'county+subdivision:86690'
+    end
+
+    it 'should truncate geography type AIANNH' do
+      CensusApi::Request.format('AIANNH', true).should == 'american+indian+area:*'
+    end
+
+    it 'should not truncate geography type CBSA' do
+      CensusApi::Request.format('CBSA', true).should == 'metropolitan+statistical+area/micropolitan+statistical+area:*'
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'vcr_setup'
+require 'api_key'
+require 'census_api'
+
+def api_key
+  RSPEC_API_KEY
+end
+
+RSpec.configure do |config|
+  config.extend VCR::RSpec::Macros
+end

data/spec/vcr_setup.rb

@@ -0,0 +1,8 @@
+require 'vcr'
+
+VCR.config do |c|
+  c.cassette_library_dir     = 'spec/vcr_cassettes'
+  c.stub_with                  :fakeweb
+  c.ignore_localhost         = true
+  c.default_cassette_options = { :record => :new_episodes }
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: census_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Ty Rauber
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hpricot
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fakeweb
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby Gem for querying the US Census Bureau API
+email:
+- tyrauber@mac.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- census_api.gemspec
+- lib/census_api.rb
+- lib/census_api/client.rb
+- lib/census_api/request.rb
+- lib/census_api/version.rb
+- lib/yml/census_shapes.yml
+- spec/api_key.sample.rb
+- spec/census_api/client_spec.rb
+- spec/census_api/request_spec.rb
+- spec/spec_helper.rb
+- spec/vcr_setup.rb
+homepage: https://github.com/tyrauber/census_api.git
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A Ruby Wrapper for the US Census Bureau API, providing the ability to query
+  both the 2010 Census and 2006-2010 ACS5 datasets.
+test_files:
+- spec/api_key.sample.rb
+- spec/census_api/client_spec.rb
+- spec/census_api/request_spec.rb
+- spec/spec_helper.rb
+- spec/vcr_setup.rb