Census API

This gem provides a Ruby wrapper around the Census Bureau API.

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.

To use this gem, install it with gem install census_api or add it to your Gemfile:

gem 'census_api'

And install it with bundle install

The US Census Bureau is currently centralizing "all data in the Census API into a uniform and consistent format across all datasets and surveys" which will result in breaking changes. Some variable names have changed and a complete variable mapping is not available.

This Readme and test suite examples have been updated. 1/10/19

Once you have the API key, you may want to store it as an environment variable.

$ export $CENSUS_API_KEY='your-api-key'

@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, {vintage: 2012, dataset: 'SF1'}) # specific vintage (year) data; defaults to 2010

To query the 2010 Census SF1 dataset, first set the dataset to 'SF1':

@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, set the dataset to 'ACS5':

@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#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:

@client.where({ fields: 'P001001', level: 'COUNTY:001', within: 'STATE:06' })

For a list of the fields available for each dataset, review the reference PDFs linked at the bottom of this document.

The 'fields' parameter is a comma separated string of SF1 field names.

The 'level' 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 'within' parameter is a set of geography types or geography. Similar to the 'level' 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 'within' 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 'within' parameter.

Retrieve fields for all States:

@client.where({ fields: 'P001001', level: 'STATE' })

Retrieve fields for California (geoid: 06):

@client.where({ fields: 'P001001', level: 'STATE:06' })

Retrieve fields for California and Alaska:

@client.where({ fields: 'P001001', level: 'STATE:06,02' })

Retrieve fields for all Counties:

@client.where({ fields: 'P001001', level: 'COUNTY' })

Retrieve fields for Counties in California:

@client.where({ fields: 'P001001', level: 'COUNTY', within: 'STATE:06' })

Retrieve fields for a specific County in California:

@client.where({ fields: 'P001001', level: 'COUNTY:001', within: 'STATE:06' })

Retrieve fields for all County Subdivisions within a specific County:

@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: 'P001001', level: 'COUSUB:86690', within: 'STATE:02+COUNTY:290' })

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: '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: 'P001001', level: 'SUBMCD:02350', within: 'STATE:72+COUNTY:127+COUSUB:79693' })

Retrieve fields for all Blocks within a specific Tract

@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: 'P001001', level: 'SUBMCD:02350', within: 'STATE:72+COUNTY:127+COUSUB:79693' })

Retrieve fields for all Tracts within a specific County:

@client.where({ fields: 'P001001', level: 'TRACT', within: 'STATE:02+COUNTY:170' })

Retrieve fields for a specific Tract within a specific County:

@client.where({ fields: 'P001001', level: 'TRACT:000101', within: 'STATE:02+COUNTY:170' })

Retrieve fields for all Block Groups within a specific Tract:

@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: 'P001001', level: 'BG:1', within: 'STATE:02+COUNTY:170+TRACT:000101' })

Retrieve fields for all Places:

@client.where({ fields: 'P001001', level: 'PLACE' })

Retrieve fields for all Places within a specific State:

@client.where({ fields: 'P001001', level: 'PLACE', within: 'STATE:06' })

Retrieve fields for a specific place within a specific State:

@client.where({ fields: 'P001001', level: 'PLACE:00135', within: 'STATE:06' })

Retrieve fields for all Alaska Native Regional Corporations:

@client.where({ fields: 'P001001', level: 'ANRC' })

Retrieve fields for all Alaska Native Regional Corporations within a specific State:

@client.where({ fields: 'P001001', level: 'ANRC', within: 'STATE:02' })

Retrieve fields for all Alaska Native Regional Corporations within a specific State:

@client.where({ fields: 'P001001', level: 'ANRC:00590', within: 'STATE:02' })

Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Land:

@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: '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: 'P001001', level: 'AIANNH:03800', within: 'STATE:02' })

Retrieve fields for all American Indian Area-Tribal Subdivisions:

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: '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: 'P001001', level: 'AITS:83127', within: 'STATE:40+AIANNH:13735' })

Retrieve fields from all Metropolitan Statistical Areas / Micropolitan Statistical Areas in a specific State:

@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: 'P001001', level: 'CBSA:11260', within: 'STATE:02' })

Retrieve fields from all Metropolitan Divisions in a specific Metropolitan Statistical Area / Micropolitan Statistical Area:

@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: '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: 'P001001', level: 'METDIV:31084', within: 'STATE:06+CBSA:31100' })

Retrieve fields from all Combined Statistical Areas in a specific State:

@client.where({ fields: 'P001001', level: 'CSA', within: 'STATE:24' })

Retrieve fields from a specific Combined Statistical Area in a specific State:

@client.where({ fields: 'P001001', level: 'CSA:428', within: 'STATE:24' })

Retrieve fields from all Congressional Districts in a specific State:

@client.where({ fields: 'P001001', level: 'CD', within: 'STATE:24' })

Retrieve fields from a specific Congressional District in a specific State:

@client.where({ fields: 'P001001', level: 'CD:01', within: 'STATE:24' })

Retrieve fields for all Counties within a specific Congressional District:

@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: 'P001001', level: 'COUNTY:003', within: 'STATE:24+CD:01' })

Retrieve fields for all Tracts within a specific Congressional District, County Remainder:

@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: 'P001001', level: 'TRACT:702100', within: 'STATE:24+CD:01+COUNTY:003' })

Retrieve fields for all County Subdivisions within a specific Congressional District, County Remainder:

@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: 'P001001', level: 'COUSUB:90100', within: 'STATE:24+CD:01+COUNTY:003' })

Retrieve fields for all Places within a specific Congressional District:

@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: 'P001001', level: 'PLACE:00125', within: 'STATE:24+CD:01' })

Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Lands within a specific Congressional District:

@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: 'P001001', level: 'AIANNH:0010', within: 'STATE:02+CD:00' })

Retrieve fields for all Alaska Native Regional Corporations within a specific Congressional District:

@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: 'P001001', level: 'AIANNH:00590', within: 'STATE:02+CD:00' })

Retrieve fields for all State Legislative Districts (Upper Chamber) within a State:

@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: 'P001001', level: 'SLDU:00A', within: 'STATE:02' })

Retrieve fields for all State Legislative Districts (Lower Chamber) within a State:

@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: 'P001001', level: 'SLDL:001', within: 'STATE:02' }) 

Retrieve fields for all Zip Code Tabulation Areas within a specific State:

@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: 'P001001', level: 'ZCTA5:99501', within: 'STATE:02' })

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.

Retrieve fields for all States:

@client.where({ fields: 'B00001_001E', level: 'STATE' })

Retrieve fields for California (geoid: 06):

@client.where({ fields: 'B00001_001E', level: 'STATE:06' })

Retrieve fields for California and Alaska:

@client.where({ fields: 'B00001_001E', level: 'STATE:06,02' })

Retrieve fields for all Counties:

@client.where({ fields: 'B00001_001E', level: 'COUNTY' })

Retrieve fields for Counties in California:

@client.where({ fields: 'B00001_001E', level: 'COUNTY', within: 'STATE:06' })

Retrieve fields for a specific County in California:

@client.where({ fields: 'B00001_001E', level: 'COUNTY:001', within: 'STATE:06' })

Retrieve fields for all County Subdivisions within a specific County:

@client.where({ fields: 'B00001_001E', level: 'COUSUB', within: 'STATE:02+COUNTY:290' })

Retrieve fields for a specific County Subdivision within a specific County:

@client.where({ fields: 'B00001_001E', level: 'COUSUB:86690', within: 'STATE:02+COUNTY:290' })

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: 'B00001_001E', level: 'SUBMCD', within: 'STATE:72+COUNTY:127+COUSUB:79693' })

Retrieve fields for a specific Subminor Civil Subdivision within a specific County Subdivision:

@client.where({ fields: 'B00001_001E', level: 'SUBMCD:02350', within: 'STATE:72+COUNTY:127+COUSUB:79693' })

Retrieve fields for all Places within a specific County Subdivision:

@client.where({ fields: 'B00001_001E', level: 'PLACE', within: 'STATE:02+COUNTY:290+COUSUB:86690' })

Retrieve fields for a specific Place within a specific County Subdivision:

@client.where({ fields: 'B00001_001E', level: 'PLACE:05750', within: 'STATE:02+COUNTY:290+COUSUB:86690' })

Retrieve fields for all Tracts within a specific Place:

@client.where({ fields: 'B00001_001E', level: 'TRACT', within: 'STATE:02+COUNTY:290+COUSUB:86690+PLACE:05750' })

Retrieve fields for a specific Tract within a specific Place:

@client.where({ fields: 'B00001_001E', level: 'TRACT:000100', within: 'STATE:02+COUNTY:290+COUSUB:86690+PLACE:05750' })

Retrieve fields for all Tracts within a specific County:

@client.where({ fields: 'B00001_001E', level: 'TRACT', within: 'STATE:02+COUNTY:170' })

Retrieve fields for a specific Tract within a specific County:

@client.where({ fields: 'B00001_001E', level: 'TRACT:000101', within: 'STATE:02+COUNTY:170' })

Retrieve fields for all Block Groups within a specific Tract:

@client.where({ fields: 'B00001_001E', level: 'BG', within: 'STATE:02+COUNTY:170+TRACT:000101' })

Retrieve fields for a specific Block Group within a specific Tract:

@client.where({ fields: 'B00001_001E', level: 'BG:1', within: 'STATE:02+COUNTY:170+TRACT:000101' })

Retrieve fields for all Places:

@client.where({ fields: 'B00001_001E', level: 'PLACE' })

Retrieve fields for all Places within a specific State:

@client.where({ fields: 'B00001_001E', level: 'PLACE', within: 'STATE:06' })

Retrieve fields for a specific place within a specific State:

@client.where({ fields: 'B00001_001E', level: 'PLACE:00135', within: 'STATE:06' })

Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Land:

@client.where({ fields: 'B00001_001E', level: 'AIANNH' })

Retrieve fields for all American Indian Area/Alaska Native Area/Hawaiian Home Land within a specific State:

@client.where({ fields: 'B00001_001E', level: 'AIANNH', within: 'STATE:02' })

Retrieve fields for a specific American Indian Area/Alaska Native Area/Hawaiian Home Land within a specific State:

DOES NOT WORK: @client.where({ fields: 'B00001_001E', level: 'AIANNH:03800', within: 'STATE:02' })

Retrieve fields from all Congressional Districts in a specific State:

@client.where({ fields: 'B00001_001E', level: 'CD', within: 'STATE:24' })

Retrieve fields from a specific Congressional District in a specific State:

@client.where({ fields: 'B00001_001E', level: 'CD:01', within: 'STATE:24' })

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