census_api 1.0.1 → 1.0.2

data/.gitignore

@@ -20,3 +20,4 @@ spec/api_key.rb
 test/tmp
 test/version_tmp
 tmp
+misc/*

data/README.md

@@ -6,7 +6,9 @@ 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.
+[http://www.census.gov/developers/tos/key_request.html][key] and follow the instructions.
+
+[key]: (http://www.census.gov/developers/tos/key_request.html)
 
 
 ## Installing the gem
@@ -17,21 +19,46 @@ To use this gem, install it with <tt>gem install census_api</tt> or add it to yo
 
 And install it with <tt>bundle install</tt>
 
-## Usage
+## Usage / Retrieving Census Data
+
+### (Optional) Set the API key as an environment variable
+
+Once you have the API key, you may want to store it as an environment variable.
+
+```sh
+$ export $CENSUS_API_KEY='your-api-key'
+```
 
-### Retrieving Census Data
+### Register a New Client
 
-First register a new Client:
+```ruby
+@client = CensusApi::Client.new(API_KEY) 
+@client = CensusApi::Client.new(ENV['CENSUS_API_KEY']) # from the environment variable
+@client = CensusApi::Client.new(API_KEY, dataset: 'SF1') # with a dataset
+```
 
-`@client = CensusApi::Client.new(API_KEY)`
+### Query a Dataset
 
-To query the 2010 Census SF1 dataset:
+To query the 2010 Census SF1 dataset, first set the dataset to 'SF1':
 
-`@client.sf1(fields, for, in*)`
+```ruby
+@client = CensusApi::Client.new(API_KEY, dataset: 'SF1') # with a dataset # during intialization
+@client.dataset = 'SF1' # or after initialization, setting the instance variable
+```
 
-To query the 2006-2010 ACS5 dataset:
+To query the 2006-2010 ACS5 dataset, set the dataset to 'ACS5':
 
-`@client.acs5(fields, for, in*)`
+```ruby
+@client = CensusApi::Client.new(API_KEY, dataset: 'ACS5') # with a dataset # during intialization
+@client.dataset = 'ACS5' # or after initialization, setting the instance variable
+```
+
+Then, use `Client#find` with the below parameters to query for Census data. For example:
+
+```ruby
+@client.find('P0010001', 'STATE:02,06')
+
+```
 
 For a list of the fields available for each dataset, review the reference PDFs linked at the bottom of this document.
 
@@ -55,39 +82,39 @@ The 'in' parameter is optional, or required, depending upon the geography type.
 
 Retrieve fields for all States:
 
-`@client.sf1('P0010001', 'STATE')`
+`@client.find('P0010001', 'STATE')`
 
 Retrieve fields for California (geoid: 06):
 
-`@client.sf1('P0010001', 'STATE:06')`
+`@client.find('P0010001', 'STATE:06')`
 
 Retrieve fields for California and Alaska:
 
-`@client.sf1('P0010001', 'STATE:06,02')`
+`@client.find('P0010001', 'STATE:06,02')`
 
 #### COUNTY - *(050) state-county*
 
 Retrieve fields for all Counties:
 
-`@client.sf1('P0010001', 'COUNTY')`
+`@client.find('P0010001', 'COUNTY')`
 
 Retrieve fields for Counties in California:
 
-`@client.sf1('P0010001', 'COUNTY', 'STATE:06')`
+`@client.find('P0010001', 'COUNTY', 'STATE:06')`
 
 Retrieve fields for a specific County in California:
 
-`@client.sf1('P0010001', 'COUNTY:001', 'STATE:06')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('P0010001', 'COUSUB:86690', 'STATE:02+COUNTY:290')`
 
 Note: You must also specify the State the County belongs to.
 
@@ -95,231 +122,231 @@ Note: You must also specify the State the County belongs to.
 
 Retrieve fields for all Subminor Civil Subdivisions within a specific County Subdivision:
 
-`@client.sf1('P0010001', 'SUBMCD', 'STATE:72+COUNTY:127+COUSUB:79693')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('P0010001', 'BG:1', 'STATE:02+COUNTY:170+TRACT:000101')`
 
 #### PLACE -*(160) state-place*
 
 Retrieve fields for all Places:
 
-`@client.sf1('P0010001', 'PLACE')`
+`@client.find('P0010001', 'PLACE')`
 
 Retrieve fields for all Places within a specific State:
 
-`@client.sf1('P0010001', 'PLACE', 'STATE:06')`
+`@client.find('P0010001', 'PLACE', 'STATE:06')`
 
 Retrieve fields for a specific place within a specific State:
 
-`@client.sf1('P0010001', 'PLACE:00135', 'STATE:06')`
+`@client.find('P0010001', 'PLACE:00135', 'STATE:06')`
 
 #### ANRC - *(260) state-alaska native regional corporation*
 
 Retrieve fields for all Alaska Native Regional Corporations:
 
-`@client.sf1('P0010001', 'ANRC')`
+`@client.find('P0010001', 'ANRC')`
 
 Retrieve fields for all Alaska Native Regional Corporations within a specific State:
 
-`@client.sf1('P0010001', 'ANRC', 'STATE:02')`
+`@client.find('P0010001', 'ANRC', 'STATE:02')`
 
 Retrieve fields for all Alaska Native Regional Corporations within a specific State:
 
-`@client.sf1('P0010001', 'ANRC:00590', 'STATE:02')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+__DOES NOT WORK__: `@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('P0010001', 'CSA', 'STATE:24')`
 
 Retrieve fields from a specific Combined Statistical Area in a specific State:
 
-`@client.sf1('P0010001', 'CSA:428', 'STATE:24')`
+`@client.find('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')`
+`@client.find('P0010001', 'CD', 'STATE:24')`
 
 Retrieve fields from a specific Congressional District in a specific State:
 
-`@client.sf1('P0010001', 'CD:01', 'STATE:24')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('P0010001', 'SLDU', 'STATE:02')`
 
 Retrieve fields for a specific State Legislative District (Upper Chamber) within a State:
 
-`@client.sf1('P0010001', 'SLDU:00A', 'STATE:02')`
+`@client.find('P0010001', 'SLDU:00A', 'STATE:02')`
 
-#### SLDU - *(620) state-state legislative district (upper chamber)*
+#### SLDU - *(620) state-state legislative district (lower chamber)*
 
 Retrieve fields for all State Legislative Districts (Lower Chamber) within a State:
 
-`@client.sf1('P0010001', 'SLDL', 'STATE:02')`
+`@client.find('P0010001', 'SLDL', 'STATE:02')`
 
-Retrieve fields for a specific State Legislative District (Upper Chamber) within a State:
+Retrieve fields for a specific State Legislative District (Lower Chamber) within a State:
 
-`@client.sf1('P0010001', 'SLDL:001', 'STATE:02')`
+`@client.find('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')`
+`@client.find('P0010001', 'ZCTA5', 'STATE:02')`
 
 Retrieve fields for a specific Zip Code Tabulation Area within a specific State:
 
-`@client.sf1('P0010001', 'ZCTA:99501', 'STATE:02')`
+`@client.find('P0010001', 'ZCTA5:99501', 'STATE:02')`
 
 ## ACS5 2010 Examples and Supported Geography
 
@@ -329,39 +356,39 @@ Querying the Census Bureau for ACS5 data is done in the same format as querying
 
 Retrieve fields for all States:
 
-`@client.acs5('B00001_001E', 'STATE')`
+`@client.find('B00001_001E', 'STATE')`
 
 Retrieve fields for California (geoid: 06):
 
-`@client.acs5('B00001_001E', 'STATE:06')`
+`@client.find('B00001_001E', 'STATE:06')`
 
 Retrieve fields for California and Alaska:
 
-`@client.acs5('B00001_001E', 'STATE:06,02')`
+`@client.find('B00001_001E', 'STATE:06,02')`
 
 #### COUNTY - *(050) state-county*
 
 Retrieve fields for all Counties:
 
-`@client.acs5('B00001_001E', 'COUNTY')`
+`@client.find('B00001_001E', 'COUNTY')`
 
 Retrieve fields for Counties in California:
 
-`@client.acs5('B00001_001E', 'COUNTY', 'STATE:06')`
+`@client.find('B00001_001E', 'COUNTY', 'STATE:06')`
 
 Retrieve fields for a specific County in California:
 
-`@client.acs5('B00001_001E', 'COUNTY:001', 'STATE:06')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('B00001_001E', 'COUSUB:86690', 'STATE:02+COUNTY:290')`
 
 Note: You must also specify the State the County belongs to.
 
@@ -369,89 +396,89 @@ Note: You must also specify the State the County belongs to.
 
 Retrieve fields for all Subminor Civil Subdivisions within a specific County Subdivision:
 
-`@client.acs5('B00001_001E', 'SUBMCD', 'STATE:72+COUNTY:127+COUSUB:79693')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('B00001_001E', 'BG:1', 'STATE:02+COUNTY:170+TRACT:000101')`
 
 #### PLACE - *(160) state-place*
 
 Retrieve fields for all Places:
 
-`@client.acs5('B00001_001E', 'PLACE')`
+`@client.find('B00001_001E', 'PLACE')`
 
 Retrieve fields for all Places within a specific State:
 
-`@client.acs5('B00001_001E', 'PLACE', 'STATE:06')`
+`@client.find('B00001_001E', 'PLACE', 'STATE:06')`
 
 Retrieve fields for a specific place within a specific State:
 
-`@client.acs5('B00001_001E', 'PLACE:00135', 'STATE:06')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('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')`
+`@client.find('B00001_001E', 'CD', 'STATE:24')`
 
 Retrieve fields from a specific Congressional District in a specific State:
 
-`@client.acs5('B00001_001E', 'CD:01', 'STATE:24')`
+`@client.find('B00001_001E', 'CD:01', 'STATE:24')`
 
 ## Additional Resources
 

data/lib/census_api/client.rb

@@ -1,19 +1,30 @@
 module CensusApi
   class Client
-    attr_reader :api_key
-    attr_reader :options
+    attr_reader   :api_key, :options
+    attr_accessor :dataset
+
+    DATASETS = %w( sf1 acs5 ) # can add more datasets as support becomes available
 
     def initialize(api_key, options = {})
+      raise ArgumentError, "You must set an api_key." unless api_key
+
+      # Use RestClient directly to determine the validity of the API Key
+      path = "http://api.census.gov/data/2010/sf1?key=#{api_key}&get=P0010001&for=state:01"
+      response = RestClient.get(path)
+
+      if response.body.include? "Invalid Key"
+        raise "'#{api_key}' is not a valid API key. Check your key for errors, or request a new one at census.gov."
+      end
+
       @api_key = api_key
-      @options = options
+      if options[:dataset]
+        @dataset = options[:dataset].downcase if DATASETS.include? options[:dataset].downcase
+      end
     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})
+    def find(fields, level, *within)
+      raise "Client has not been assigned a dataset to query. Try @client.dataset = 'SF1' or anything from #{DATASETS}" if self.dataset.nil?
+      Request.find(dataset, {key: @api_key, fields: fields, level: level, within: within})
     end
   end
-end
+end

data/lib/census_api/request.rb

@@ -12,22 +12,25 @@ module CensusApi
     
     CENSUS_URL = "http://api.census.gov/data/2010"
 
+    def initialize(url, source, options)
+      path = "#{url}/#{source}?#{options.to_params}"
+      @response = RestClient.get(path) do |response, request, result, &block|
+        response
+      end
+      return @response
+    end
+
+
     def self.find(source, options = {})
-      flds = options[:fields].split(",").push("NAME").join(",")
-      params = { :key => options[:key], :get => flds, :for => format(options[:level],false) }
+      fields = options[:fields]
+      fields = fields.split(",").push("NAME").join(",") if fields.kind_of? String
+      fields = fields.push("NAME").join(",") if fields.kind_of? Array
+      params = { :key => options[:key], :get => fields, :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
@@ -36,39 +39,39 @@ module CensusApi
           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]}
+          return {:code => @response.code, :message=> "Invalid API key or request", :location=> @response.headers[:location], :body => @response.body}
         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(File.dirname(__FILE__).to_s + '/../yml/census_shapes.yml').each{|k,v| @@census_shapes[k] = v}
-      return @@census_shapes
+      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(File.dirname(__FILE__).to_s + '/../yml/census_shapes.yml').each{|k,v| @@census_shapes[k] = v}
+        return @@census_shapes
+      end
+      
     end
-    
   end
-end
 
 class Hash
-   def to_p
+   def to_params
      self.map { |k,v| "#{k}=#{v}" }.join("&")
    end
-end
+end

data/lib/census_api/version.rb

@@ -1,3 +1,3 @@
 module CensusApi
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/lib/census_api.rb

@@ -1,5 +1,3 @@
 require 'rubygems'
 
-%w(version client request).each do |file|
-  require File.join(File.dirname(__FILE__), 'census_api', file)
-end
+Dir["./lib/census_api/*"].each { |file| require file }

data/spec/census_api/client_spec.rb

@@ -2,27 +2,43 @@ require 'spec_helper'
 
 describe CensusApi::Client do
 
-  it 'should not initialize without an api_key' do
-    lambda { CensusApi::Client.new }.should raise_error
-  end
+  describe "client initialization" do
 
-  it 'should initialize with an api_key' do
-    @client = CensusApi::Client.new(api_key)
-    @client.api_key.should == api_key
-  end
+    use_vcr_cassette "initialize_client"
 
-  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])
+    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
   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])
+  describe "client and dataset initialization" do
+
+    use_vcr_cassette "initialize_client_and_dataset"
+
+    it 'should initialize with an api_key and dataset' do
+      dataset = 'SF1'
+      @client = CensusApi::Client.new(api_key, dataset: dataset)
+      @client.api_key.should == api_key
+      @client.dataset.should == dataset.downcase
+    end
+
+    it 'should request sf1' do
+      source, options = 'sf1', {:key=> api_key, :fields => 'P0010001', :level => 'STATE:06', :within=>[]}
+      @client = CensusApi::Client.new(api_key, dataset: source)
+      CensusApi::Request.should_receive(:find).with(@client.dataset, options)
+      @client.find(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, dataset: source)
+      CensusApi::Request.should_receive(:find).with(@client.dataset, options)
+      @client.find(options[:fields], options[:level])
+    end
   end
-  
 end

data/spec/census_api/request_spec.rb

@@ -9,7 +9,7 @@ describe CensusApi::Request do
       ]},
       {:source => 'acs5', :field => 'B00001_001E', :results =>[
         {"B00001_001E"=>"2330290", "name"=>"California", "state"=>"06"},
-        {"B00001_001E"=>"92854", "name"=>"Alameda County", "state"=>"06", "county"=>"001"}
+        {"B00001_001E"=>"92854", "name"=>"Alameda County, California", "state"=>"06", "county"=>"001"}
       ]}
     ].each do |test|
     

data/spec/vcr_setup.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: census_api
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-12 00:00:00.000000000 Z
+date: 2013-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client