Package: cenpy
An interface to explore and query the US Census API and return Pandas
Dataframes. This package is intended for exploratory data
analysis and draws inspiration from sqlalchemy-like interfaces andacs.R. With separate APIs for application developers and folks who
only want to get their data quickly & painlessly,cenpyshould meet
the needs of most who aim to get US Census Data from Python.A few examples are available fromour website:getting data quickly using Cenpy.analyzing segregation over time & across space using cenpy and segregationa road to frictionless urban data science using cenpy and osmnxdeveloper building blocks.piecing together the developer building blocks (by @dfolch)InstallationCenpy is easiest to install usingconda, a commonly-used package manager for scientific python. First,install Anaconda.Then,cenpyis available on theconda-forgechannel:conda install -c conda-forge cenpyAlternatively, you can install cenpyviapip, the python package manager, if you have installedgeopandasandrtree:pip install cenpyFor UsersMost of the time, users want a simple and direct interface to the US Census Bureau’s main products: the 2010 Census and the American Community Survey. Fortunately, cenpy provides a direct interface to these products. For instance, the American Community Survey’s most recent 5-year estimates can be accessed using:import cenpy
acs = cenpy.products.ACS()
acs.from_place('Chicago, IL')Likewise, the decennial census can be accessed using:import cenpy
decennial = cenpy.products.Decennial2010()
decennial.from_place('Seattle, WA')For more information on how the product API works, consult thenotebook on the topic.For DevelopersThe API reference is available atcenpy-devs.github.io/cenpy. Theproductsare typically what most end-users will want to interact with. If you want more fine-grained access to the USCB APIs, you will likely want to build on top ofAPIConnectionandTigerConnection.At a high level, theAPIConnectionobject connects to resources exposed on the US Census Bureau’s API athttps://api.census.gov/data.json. Its methods and relevant utilities are defined incenpy.remote. TheTigerConnectionwraps one map service exposed athttp://tigerweb.geo.census.gov/arcgis/rest/services/TIGERweband is defined incenpy.tiger. EachTigerConnectionis composed of manyESRILayerobjects, which wrap an individual geography within the ESRI map service. For instance, an ACSTigerConnectionmay contain State, County, and TractESRILayerobjects within theirlayerattribute.To use the developer-focused API, you can create anAPIConnectionusing its shortcode:cxn = cenpy.remote.APIConnection('DECENNIALSF12010')Check the variables required and geographies supported:cxn.variables #is a pandas dataframe containing query-able vbls
cxn.geographies #is a pandas dataframe containing query-able geographiesNote that some geographies (like tract) have requirements higher in the hierarchy
that you’ll have to specify for the query to work.The structure of the query function maps to the Census API’s use ofget,for, andin. The main arguments for the query function
arecols,geo_unitandgeo_filter, and map back to those predicates, respectively. If more predicates are required for the
search, they can be added as keyword arguments at the end of the query.Thecolsargument must be a list of columns to retrieve from the
dataset. Then, you must specify thegeo_unitandgeo_filter,
which providewhatthe unit of aggregation should be andwherethe
units should be.geo_unitmust be a string containing the unit of
analysis and an identifier. For instance, if you want all counties in
Arizona, you specifygeo_unit ='county:*'andgeo_filter ={'state':'04'}.To create aTigerConnection:cxn = cenpy.tiger.TigerConnection('tigerWMS_ACS2013')Then, all of theESRILayerobjects are contained in thelayerattribute:cxn.layersthecxn.querymethod passes the relevant query down to the chosen layer and returns ageopandasdataframe. The actual query is structured likeSQL, and follows theESRI documentation.ContributingTo contribute tocenpy:Usecenpy! Every user is a contributor in kind. If you feel like it,file an issue:to tell us how you usecenpy.to post a code snippit, a jupyter notebook, or whatever you can.to tell us about yourblog posts!to ask questions about how you might use census data from Python, and we’ll try to help.If you’re usingcenpyand something goes wrong,file an issuetelling us:what you want that is not incenpyor doesn’t work well in other packageswhat functionality incenpyisn’t working how you believe it oughtwhat in the documentation isn’t spelled correctly or is confusingForkthecenpy-devs/cenpygithub repository, make changes, and send us apull requestToDo:A product incenpy.productsfor County Business Statistics