census_api 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c6080f79695746c9da16b9a6a39eaaeb8f8932d
-  data.tar.gz: bb8d0ce3088e0c78fc36beba6b8bed9b1b95a604
+  metadata.gz: d339bee3037ab0d8bb8392064a3cc83ab41aa4ae
+  data.tar.gz: bc7c082251040e2010950612a3b4c7406d59876f
 SHA512:
-  metadata.gz: bde1d5a14e91651c1b29156fa4ddb23a9fc05c5206a2a42d9f28b7e2e968d38e0a7ec11bb696f619d6c6f3253f5956738d033e85fdae9103ce657d49f9b32889
-  data.tar.gz: 88a0931b9c90edde163cf67c6711e2b483ae0f5b951a9585e49912007c0a9ae002843f62e1aa9ac4c2c0b63f39a35a79a32b70f3cb9c58beba612b3197914d7f
+  metadata.gz: 0e963d9624c8ba6b03023736dcbfbc53902f782a8f6cc347f55fa0e959a025c7c1671a1f5f04f4e48df54f294e5ceadbfc766fc3caf5efc0e61c4b2fd9851688
+  data.tar.gz: 9e02121dbae295a01b861741ccdddefdeb8f26e113f47e13fc1d8756fcc15434ce71e52d9e667966f44dc01e0ca4cb0fe2262cfd3494c1c17dbaedf7d838d79c

data/.travis.yml

@@ -0,0 +1,12 @@
+sudo: false
+language: ruby
+bundler_args: ''
+rvm:
+  - 2.5.1
+  - 2.4.4
+  - 2.3.4
+  - 2.3.7
+before_install:
+  - gem install bundler --version '~> 2.0.1'
+script: "rake"
+

data/README.md

@@ -5,11 +5,8 @@ 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][key] and follow the instructions.
-
-[key]: (http://www.census.gov/developers/tos/key_request.html)
-
+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](http://www.census.gov/developers/tos/key_request.html) and follow the instructions.
 
 ## Installing the gem
 
@@ -19,6 +16,12 @@ 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>
 
+## Notice: Breaking API Changes
+
+The US Census Bureau is currently centralizing ["all data in the Census API into a uniform and consistent format across all datasets and surveys"](https://www.census.gov/data/developers/updates/api-format-changes--sf1-2010.html) which will result in breaking changes.  Some variable names have changed and [a complete variable mapping is not available.](https://www.census.gov/data/developers/updates/api-format-changes--sf1-2010.html)
+
+This Readme and test suite examples have been updated.  1/10/19
+
 ## Usage / Retrieving Census Data
 
 ### (Optional) Set the API key as an environment variable
@@ -57,7 +60,7 @@ To query the 2006-2010 ACS5 dataset, set the dataset to 'ACS5':
 Then, use `Client#where` with an options hash to query for Census data. The fields and level parameters are required. The within parameter is optional and scopes the query. For example:
 
 ```ruby
-@client.where({ fields: 'P0010001', level: 'COUNTY:001', within: 'STATE:06' })
+@client.where({ fields: 'P001001', level: 'COUNTY:001', within: 'STATE:06' })
 
 ```
 
@@ -83,39 +86,39 @@ The 'within' parameter is optional, or required, depending upon the geography ty
 
 Retrieve fields for all States:
 
-`@client.where({ fields: 'P0010001', level: 'STATE' })`
+`@client.where({ fields: 'P001001', level: 'STATE' })`
 
 Retrieve fields for California (geoid: 06):
 
-`@client.where({ fields: 'P0010001', level: 'STATE:06' })`
+`@client.where({ fields: 'P001001', level: 'STATE:06' })`
 
 Retrieve fields for California and Alaska:
 
-`@client.where({ fields: 'P0010001', level: 'STATE:06,02' })`
+`@client.where({ fields: 'P001001', level: 'STATE:06,02' })`
 
 #### COUNTY - *(050) state-county*
 
 Retrieve fields for all Counties:
 
-`@client.where({ fields: 'P0010001', level: 'COUNTY' })`
+`@client.where({ fields: 'P001001', level: 'COUNTY' })`
 
 Retrieve fields for Counties in California:
 
-`@client.where({ fields: 'P0010001', level: 'COUNTY', within: 'STATE:06' })`
+`@client.where({ fields: 'P001001', level: 'COUNTY', within: 'STATE:06' })`
 
 Retrieve fields for a specific County in California:
 
-`@client.where({ fields: 'P0010001', level: 'COUNTY:001', within: 'STATE:06' })`
+`@client.where({ fields: 'P001001', level: 'COUNTY:001', within: 'STATE:06' })`
 
 #### COUSUB - *(060) state-county-county subdivision*
 
 Retrieve fields for all County Subdivisions within a specific County:
 
-`@client.where({ fields: 'P0010001', level: 'COUSUB', within: 'STATE:02+COUNTY:290' })`
+`@client.where({ fields: 'P001001', level: 'COUSUB', within: 'STATE:02+COUNTY:290' })`
 
 Retrieve fields for a specific County Subdivision within a specific County:
 
-`@client.where({ fields: 'P0010001', level: 'COUSUB:86690', within: 'STATE:02+COUNTY:290' })`
+`@client.where({ fields: 'P001001', level: 'COUSUB:86690', within: 'STATE:02+COUNTY:290' })`
 
 Note: You must also specify the State the County belongs to.
 
@@ -123,231 +126,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.where({ fields: 'P0010001', level: 'SUBMCD', within: 'STATE:72+COUNTY:127+COUSUB:79693' })`
+`@client.where({ fields: 'P001001', level: 'SUBMCD', within: 'STATE:72+COUNTY:127+COUSUB:79693' })`
 
 Retrieve fields for a specific Subminor Civil Subdivisions within a specific County Subdivision:
 
-`@client.where({ fields: 'P0010001', level: 'SUBMCD:02350', within: 'STATE:72+COUNTY:127+COUSUB:79693' })`
+`@client.where({ fields: 'P001001', level: 'SUBMCD:02350', within: 'STATE:72+COUNTY:127+COUSUB:79693' })`
 
 #### TABBLOCK - *(101) state-county-tract-block*
 
 Retrieve fields for all Blocks within a specific Tract
 
-`@client.where({ fields: 'P0010001', level: 'TABBLOCK', within: 'STATE:02+COUNTY:290+TRACT:00100' })`
+`@client.where({ fields: 'P001001', level: 'TABBLOCK', within: 'STATE:02+COUNTY:290+TRACT:00100' })`
 
 Retrieve fields for a specific Subminor Civil Subdivisions within a specific County Subdivision:
 
-`@client.where({ fields: 'P0010001', level: 'SUBMCD:02350', within: 'STATE:72+COUNTY:127+COUSUB:79693' })`
+`@client.where({ fields: 'P001001', level: 'SUBMCD:02350', within: 'STATE:72+COUNTY:127+COUSUB:79693' })`
 
 #### TRACT - *(140) state-county-tract*
 
 Retrieve fields for all Tracts within a specific County:
 
-`@client.where({ fields: 'P0010001', level: 'TRACT', within: 'STATE:02+COUNTY:170' })`
+`@client.where({ fields: 'P001001', level: 'TRACT', within: 'STATE:02+COUNTY:170' })`
 
 Retrieve fields for a specific Tract within a specific County:
 
-`@client.where({ fields: 'P0010001', level: 'TRACT:000101', within: 'STATE:02+COUNTY:170' })`
+`@client.where({ fields: 'P001001', level: 'TRACT:000101', within: 'STATE:02+COUNTY:170' })`
 
 #### BG - *(150) state-county- tract-block group*
 
 Retrieve fields for all Block Groups within a specific Tract:
 
-`@client.where({ fields: 'P0010001', level: 'BG', within: 'STATE:02+COUNTY:170+TRACT:000101' })`
+`@client.where({ fields: 'P001001', level: 'BG', within: 'STATE:02+COUNTY:170+TRACT:000101' })`
 
 Retrieve fields for a specific Block Group within a specific Tract:
 
-`@client.where({ fields: 'P0010001', level: 'BG:1', within: 'STATE:02+COUNTY:170+TRACT:000101' })`
+`@client.where({ fields: 'P001001', level: 'BG:1', within: 'STATE:02+COUNTY:170+TRACT:000101' })`
 
 #### PLACE -*(160) state-place*
 
 Retrieve fields for all Places:
 
-`@client.where({ fields: 'P0010001', level: 'PLACE' })`
+`@client.where({ fields: 'P001001', level: 'PLACE' })`
 
 Retrieve fields for all Places within a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'PLACE', within: 'STATE:06' })`
+`@client.where({ fields: 'P001001', level: 'PLACE', within: 'STATE:06' })`
 
 Retrieve fields for a specific place within a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'PLACE:00135', within: 'STATE:06' })`
+`@client.where({ fields: 'P001001', level: 'PLACE:00135', within: 'STATE:06' })`
 
 #### ANRC - *(260) state-alaska native regional corporation*
 
 Retrieve fields for all Alaska Native Regional Corporations:
 
-`@client.where({ fields: 'P0010001', level: 'ANRC' })`
+`@client.where({ fields: 'P001001', level: 'ANRC' })`
 
 Retrieve fields for all Alaska Native Regional Corporations within a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'ANRC', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'ANRC', within: 'STATE:02' })`
 
 Retrieve fields for all Alaska Native Regional Corporations within a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'ANRC:00590', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'ANRC:00590', within: '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.where({ fields: 'P0010001', level: 'AIANNH' })`
+`@client.where({ fields: 'P001001', level: 'AIANNH' })`
 
 Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Land within a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'AIANNH', within: 'STATE:02 }')`
+`@client.where({ fields: 'P001001', level: 'AIANNH', within: 'STATE:02 }')`
 
 Retrieve fields for a specific American Indian Area/Alaska Native Area/Hawaiian Home Land within a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'AIANNH:03800', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'AIANNH:03800', within: 'STATE:02' })`
 
 #### AITS - *(281) state-american indian area-tribal subdivision*
 
 Retrieve fields for all American Indian Area-Tribal Subdivisions:
 
-__DOES NOT WORK__: `@client.where({ fields: 'P0010001', level: 'AITS' })`
+__DOES NOT WORK__: `@client.where({ fields: 'P001001', level: 'AITS' })`
 
 Retrieve fields for all American Indian Area-Tribal Subdivisions in a specific American Indian Area:
 
-`@client.where({ fields: 'P0010001', level: 'AITS', within: 'STATE:40+AIANNH:13735' })`
+`@client.where({ fields: 'P001001', level: 'AITS', within: 'STATE:40+AIANNH:13735' })`
 
 Retrieve fields for a specific American Indian Area-Tribal Subdivision in a specific American Indian Area:
 
-`@client.where({ fields: 'P0010001', level: 'AITS:83127', within: 'STATE:40+AIANNH:13735' })`
+`@client.where({ fields: 'P001001', level: 'AITS:83127', within: '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.where({ fields: 'P0010001', level: 'CBSA', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'CBSA', within: 'STATE:02' })`
 
 Retrieve fields from a specific Metropolitan Statistical Areas / Micropolitan Statistical Areas in a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'CBSA:11260', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'CBSA:11260', within: '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.where({ fields: 'P0010001', level: 'METDIV', within: 'STATE:06+CBSA:31100' })`
+`@client.where({ fields: 'P001001', level: 'METDIV', within: 'STATE:06+CBSA:31100' })`
 
 Retrieve fields from all Metropolitan Division in a specific Metropolitan Statistical Area / Micropolitan Statistical Area:
 
-`@client.where({ fields: 'P0010001', level: 'METDIV', within: 'STATE:06+CBSA:31100' })`
+`@client.where({ fields: 'P001001', level: 'METDIV', within: 'STATE:06+CBSA:31100' })`
 
 Retrieve fields from a specific Metropolitan Division in a specific Metropolitan Statistical Area / Micropolitan Statistical Area:
 
-`@client.where({ fields: 'P0010001', level: 'METDIV:31084', within: 'STATE:06+CBSA:31100' })`
+`@client.where({ fields: 'P001001', level: 'METDIV:31084', within: 'STATE:06+CBSA:31100' })`
 
 #### CSA - *(340) - state-combined statistical area*
 
 Retrieve fields from all Combined Statistical Areas in a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'CSA', within: 'STATE:24' })`
+`@client.where({ fields: 'P001001', level: 'CSA', within: 'STATE:24' })`
 
 Retrieve fields from a specific Combined Statistical Area in a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'CSA:428', within: 'STATE:24' })`
+`@client.where({ fields: 'P001001', level: 'CSA:428', within: 'STATE:24' })`
 
 #### CD - *(500) state-congressional district*
 
 Retrieve fields from all Congressional Districts in a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'CD', within: 'STATE:24' })`
+`@client.where({ fields: 'P001001', level: 'CD', within: 'STATE:24' })`
 
 Retrieve fields from a specific Congressional District in a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'CD:01', within: 'STATE:24' })`
+`@client.where({ fields: 'P001001', level: 'CD:01', within: 'STATE:24' })`
 
 #### COUNTY (Remainder) - *(510) state-congressional district-county*
 
 Retrieve fields for all Counties within a specific Congressional District:
 
-`@client.where({ fields: 'P0010001', level: 'COUNTY', within: 'STATE:24+CD:01' })`
+`@client.where({ fields: 'P001001', level: 'COUNTY', within: 'STATE:24+CD:01' })`
 
 Retrieve fields for a specific County within a specific Congressional District:
 
-`@client.where({ fields: 'P0010001', level: 'COUNTY:003', within: 'STATE:24+CD:01' })`
+`@client.where({ fields: 'P001001', level: 'COUNTY:003', within: '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.where({ fields: 'P0010001', level: 'TRACT', within: 'STATE:24+CD:01+COUNTY:003' })`
+`@client.where({ fields: 'P001001', level: 'TRACT', within: 'STATE:24+CD:01+COUNTY:003' })`
 
 Retrieve fields for a specific County within a specific Congressional District, County Remainder:
 
-`@client.where({ fields: 'P0010001', level: 'TRACT:702100', within: 'STATE:24+CD:01+COUNTY:003' })`
+`@client.where({ fields: 'P001001', level: 'TRACT:702100', within: '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.where({ fields: 'P0010001', level: 'COUSUB', within: 'STATE:24+CD:01+COUNTY:003' })`
+`@client.where({ fields: 'P001001', level: 'COUSUB', within: 'STATE:24+CD:01+COUNTY:003' })`
 
 Retrieve fields for a specific County Subdivision within a specific Congressional District, County Remainder:
 
-`@client.where({ fields: 'P0010001', level: 'COUSUB:90100', within: 'STATE:24+CD:01+COUNTY:003' })`
+`@client.where({ fields: 'P001001', level: 'COUSUB:90100', within: 'STATE:24+CD:01+COUNTY:003' })`
 
 #### PLACE (Remainder) - *(531) state congressional district-place*
 
 Retrieve fields for all Places within a specific Congressional District:
 
-`@client.where({ fields: 'P0010001', level: 'PLACE', within: 'STATE:24+CD:01' })`
+`@client.where({ fields: 'P001001', level: 'PLACE', within: 'STATE:24+CD:01' })`
 
 Retrieve fields for a specific Place within a specific Congressional District, County Remainder:
 
-`@client.where({ fields: 'P0010001', level: 'PLACE:00125', within: 'STATE:24+CD:01' })`
+`@client.where({ fields: 'P001001', level: 'PLACE:00125', within: '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.where({ fields: 'P0010001', level: 'AIANNH', within: 'STATE:02+CD:00' })`
+`@client.where({ fields: 'P001001', level: 'AIANNH', within: 'STATE:02+CD:00' })`
 
 Retrieve fields for a specific American Indian Area/Alaska Native Area/Hawaiian Home Land  within a specific Congressional District:
 
-__DOES NOT WORK__: `@client.where({ fields: 'P0010001', level: 'AIANNH:0010', within: 'STATE:02+CD:00' })`
+__DOES NOT WORK__: `@client.where({ fields: 'P001001', level: 'AIANNH:0010', within: '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.where({ fields: 'P0010001', level: 'AIANNH', within: 'STATE:02+CD:00' })`
+`@client.where({ fields: 'P001001', level: 'AIANNH', within: 'STATE:02+CD:00' })`
 
 Retrieve fields for a specific Alaska Native Regional Corporation  within a specific Congressional District:
 
-`@client.where({ fields: 'P0010001', level: 'AIANNH:00590', within: 'STATE:02+CD:00' })`
+`@client.where({ fields: 'P001001', level: 'AIANNH:00590', within: '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.where({ fields: 'P0010001', level: 'SLDU', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'SLDU', within: 'STATE:02' })`
 
 Retrieve fields for a specific State Legislative District (Upper Chamber) within a State:
 
-`@client.where({ fields: 'P0010001', level: 'SLDU:00A', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'SLDU:00A', within: 'STATE:02' })`
 
 #### SLDU - *(620) state-state legislative district (lower chamber)*
 
 Retrieve fields for all State Legislative Districts (Lower Chamber) within a State:
 
-`@client.where({ fields: 'P0010001', level: 'SLDL', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'SLDL', within: 'STATE:02' })`
 
 Retrieve fields for a specific State Legislative District (Lower Chamber) within a State:
 
-`@client.where({ fields: 'P0010001', level: 'SLDL:001', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'SLDL:001', within: 'STATE:02' })`
 
 #### ZCTA5 - *(871) state-zip code tabulation area*
 
 Retrieve fields for all Zip Code Tabulation Areas within a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'ZCTA5', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'ZCTA5', within: 'STATE:02' })`
 
 Retrieve fields for a specific Zip Code Tabulation Area within a specific State:
 
-`@client.where({ fields: 'P0010001', level: 'ZCTA5:99501', within: 'STATE:02' })`
+`@client.where({ fields: 'P001001', level: 'ZCTA5:99501', within: 'STATE:02' })`
 
 ## ACS5 2010 Examples and Supported Geography
 

data/Rakefile

@@ -1 +1,9 @@
-require 'bundler/gem_tasks'
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task test: :spec
+
+task default: :test
+

data/census_api.gemspec

@@ -22,8 +22,11 @@ Gem::Specification.new do |gem|
   gem.require_paths = ['lib']
 
   gem.add_runtime_dependency 'http'
+  gem.add_development_dependency 'bundler', '~> 2.0.1'
+  gem.add_development_dependency 'rake'
   gem.add_development_dependency 'rspec'
-  gem.add_development_dependency 'webmock', '< 2.0'
-  gem.add_development_dependency 'vcr'
+  gem.add_development_dependency 'webmock', '>= 3.4.2'
+  gem.add_development_dependency 'vcr', '>= 4.0'
   gem.add_development_dependency 'rubocop'
+  gem.add_development_dependency 'rest-client'
 end

data/lib/census_api/client.rb

@@ -29,7 +29,7 @@ module CensusApi
       [:fields, :level].each do |f|
         fail ArgumentError, "#{f} is a requied parameter" if options[f].nil?
       end
-      options[:within] = [options[:within]]
+      options[:within] = [options[:within]] unless options[:within].nil?
       Request.find(dataset, options)
     end
 

data/lib/census_api/request.rb

@@ -11,6 +11,19 @@ module CensusApi
     attr_accessor :response
 
     def initialize(vintage, source, options)
+      api_changes = [
+        {source: 'acs1', from: 2012, to: 2015, new_endpoint: 'acs/acs1'},
+        #{source: 'acs3', from: 2012, to: 2013, new_endpoint: 'acs/acs3'},
+        {source: 'acs5', from: 2010, to: 2015, new_endpoint: 'acs/acs5'},
+        {source: 'acsse', from: 2014, to: 2015, new_endpoint: 'acs/acsse'},
+        {source: 'sf1', from: 2010, to: 2010, new_endpoint: 'dec/sf1'}
+      ]
+      route = api_changes.detect do |a| 
+        a[:source] == source && a[:from] <= vintage.to_i && a[:to] >= vintage.to_i
+      end
+      if route
+        source = route[:new_endpoint]
+      end
       uri = "/data/#{vintage}/#{source}?#{to_params(options)}"
       @response = $census_connection.get(uri.to_s)
       @response.flush
@@ -20,12 +33,13 @@ module CensusApi
       fields = options[:fields]
       fields = fields.split(',').push('NAME').join(',') if fields.is_a? String
       fields = fields.push('NAME').join(',') if fields.is_a? Array
-      level  = format(options[:level], false, source)
-      params = { key: options[:key], get: fields, for: level }
-      unless (options[:within].nil? || (options[:within].is_a?(Array) && options[:within].compact.empty?))
-        params.merge!(in: format(options[:within][0], true, source))
+      level  = format(options[:level])
+      params = { get: fields, for: level }
+      unless options[:within].nil? || (options[:within].is_a?(Array) && options[:within].empty?)
+        params.merge!(in: format(options[:within].join("+")))
       end
       options.merge!(vintage: 2010) unless options[:vintage]
+      params.merge!(key: options[:key]) if !!(options[:key])
       request = new(options[:vintage], source, params)
       request.parse_response
     end
@@ -61,22 +75,18 @@ module CensusApi
       }
     end
 
-    def self.format(str, truncate, source=nil)
-      result = str.split('+').map do |s|
+    def self.format(str)
+      str.split("+").map do |s|
         s = s.match(':') ? s.split(':') : [s, '*']
-        shp = shapes[s[0].upcase]
-        name = shp[[source,'name'].compact.join("_")]||shp['name']
-        s.shift && s.unshift(name.downcase.gsub(' ', '+')) unless shp.nil?
-        s.unshift(s.shift.split('/')[0]) if !s[0].scan('home+land').empty? && truncate
-        s.join(':')
-      end
-      result.join('+')
+        name = (shapes[s[0]]['attribute'] rescue s[0]).gsub(/\s/, '%20')
+        s.shift && s.unshift(name) && s.join(':')
+      end.join("%20")
     end
 
     def self.shapes
       return @@census_shapes if defined?(@@census_shapes)
       @@census_shapes = {}
-      path = "#{File.dirname(__FILE__)}/../yml/census_shapes.yml"
+      path = "#{File.dirname(__FILE__)}/../data/census_shapes.yml"
       YAML.load_file(path).each { |k, v| @@census_shapes[k] = v }
       @@census_shapes
     end