{"id":13446463,"url":"https://github.com/datamade/census","last_synced_at":"2025-12-12T00:59:49.003Z","repository":{"id":3531434,"uuid":"4590863","full_name":"datamade/census","owner":"datamade","description":"A Python wrapper for the US Census API. ","archived":false,"fork":false,"pushed_at":"2025-04-08T15:45:26.000Z","size":215,"stargazers_count":660,"open_issues_count":39,"forks_count":145,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-14T13:58:27.642Z","etag":null,"topics":["census","census-api","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datamade.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-06-07T21:44:36.000Z","updated_at":"2025-04-13T18:39:16.000Z","dependencies_parsed_at":"2023-02-16T23:00:35.148Z","dependency_job_id":"74442d89-d82f-4970-84a1-0fed8ef34daf","html_url":"https://github.com/datamade/census","commit_stats":{"total_commits":165,"total_committers":32,"mean_commits":5.15625,"dds":0.6848484848484848,"last_synced_commit":"b3d7c1882416b6ece5b2584f02750a87f4440e95"},"previous_names":["sunlightlabs/census"],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datamade%2Fcensus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datamade%2Fcensus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datamade%2Fcensus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datamade%2Fcensus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datamade","download_url":"https://codeload.github.com/datamade/census/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076850,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["census","census-api","python"],"created_at":"2024-07-31T05:00:53.536Z","updated_at":"2025-12-12T00:59:48.933Z","avatar_url":"https://github.com/datamade.png","language":"Python","readme":"======\ncensus\n======\n.. image:: https://github.com/datamade/census/workflows/Python%20package/badge.svg\n \n\nA simple wrapper for the United States Census Bureau's API.\n\nProvides access to ACS and SF1 data sets.\n\nInstall\n=======\n\n::\n\n    pip install census\n\nYou may also want to install a complementary library, `us \u003chttps://pypi.python.org/pypi/us\u003e`_, which help you figure out the\n`FIPS \u003chttps://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code\u003e`_ codes for many geographies. We use it in the examples below.\n\n::\n\n   pip install us\n\nUsage\n=====\n\nFirst, get yourself a `Census API key \u003chttps://api.census.gov/data/key_signup.html\u003e`_.\n\n::\n\n    from census import Census\n    from us import states\n\n    c = Census(\"MY_API_KEY\")\n    c.acs5.get(('NAME', 'B25034_010E'),\n              {'for': 'state:{}'.format(states.MD.fips)})\n\nThe call above will return the name of the geographic area and the number of\nhomes that were built before 1939 for the state of Maryland. Helper methods have\nbeen created to simplify common geometry calls::\n\n    c.acs5.state(('NAME', 'B25034_010E'), states.MD.fips)\n\nFull details on geometries and the states module can be found below.\n\nThe get method is the core data access method on both the ACS and SF1 data sets.\nThe first parameter is either a single string column or a tuple of columns. The\nsecond parameter is a geoemtry dict with a `for` key and on option `in` key. The\n`for` argument accepts a `\"*\"` wildcard character or `Census.ALL`. The wildcard\nis not valid for the `in` parameter.\n\nBy default, the year for a dataset is the most recent year available. To access earlier data,\npass a year parameter to the API call::\n\n    c.acs5.state(('NAME', 'B25034_010E'), states.MD.fips, year=2010)\n\nThe default year may also be set client-wide::\n\n    c = Census(\"MY_API_KEY\", year=2010)\n\n\nDetailed information about the API can be found at the `Census Data API User Guide \u003chttps://www.census.gov/data/developers/guidance/api-user-guide.html\u003e`_.\n\nDatasets\n========\n\nFor each dataset, the first year listed is the default.\n\n* acs5: `ACS 5 Year Estimates \u003chttps://www.census.gov/data/developers/data-sets/acs-5year.html\u003e`_ (2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012, 2011, 2010, 2009)\n* acs3: `ACS 3 Year Estimates \u003chttps://www.census.gov/data/developers/data-sets/acs-3year.html\u003e`_ (2013, 2012)\n* acs1: `ACS 1 Year Estimates \u003chttps://www.census.gov/data/developers/data-sets/acs-1year.html\u003e`_ (2023, 2022, 2021, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012, 2011)\n* acs5dp: `ACS 5 Year Estimates, Data Profiles  \u003chttps://www.census.gov/data/developers/data-sets/acs-5year.html\u003e`_ (2023, 2022, 2021, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012, 2011, 2010, 2009)\n* acs3dp: `ACS 3 Year Estimates, Data Profiles \u003chttps://www.census.gov/data/developers/data-sets/acs-3year.html\u003e`_ (2013, 2012)\n* acs1dp: `ACS 1 Year Estimates, Data Profiles \u003chttps://www.census.gov/data/developers/data-sets/acs-1year.html\u003e`_ (2023, 2022, 2021, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012, 2011)\n* acs5st: `ACS 5 Year Estimates, Subject Tables \u003chttps://www.census.gov/data/developers/data-sets/acs-5year.html\u003e`_ (2023, 2022, 2021, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012, 2011, 2010, 2009)\n* sf1: `Census Summary File 1 \u003chttps://www.census.gov/data/datasets/2010/dec/summary-file-1.html\u003e`_ (2010)\n* pl: `Redistricting Data Summary File \u003chttps://www.census.gov/programs-surveys/decennial-census/about/rdo/summary-files.2020.html\u003e`_ (2020, 2010, 2000) \n\n\nGeographies\n===========\n\nThe API supports a wide range of geographic regions. The specification of these\ncan be quite complicated so a number of convenience methods are provided. Refer to the `Census API documentation \u003chttps://www.census.gov/data/developers/guidance/api-user-guide.html\u003e`_\nfor more geographies beyond the convenience methods.\n\n*Not all geographies are supported in all years. Calling a convenience method\nwith a year that is not supported will raise census.UnsupportedYearException.*\n\n`Geographic relationship files \u003chttps://www.census.gov/geo/maps-data/data/relationship.html\u003e`_ are provided on the Census developer site as a tool to help users compare the geographies from the 1990, 2000 and 2010 Censuses. From these files, data users may determine how geographies from one Census relate to those from the prior Census.\n\nACS5 Geographies\n----------------\n\n* state(fields, state_fips)\n* state_county(fields, state_fips, county_fips)\n* state_county_blockgroup(fields, state_fips, county_fips, blockgroup)\n* state_county_subdivision(fields, state_fips, county_fips, subdiv_fips)\n* state_county_tract(fields, state_fips, county_fips, tract)\n* state_place(fields, state_fips, place)\n* state_congressional_district(fields, state_fips, congressional_district)\n* state_legislative_district_upper(fields, state_fips, legislative_district)\n* state_legislative_district_lower(fields, state_fips, legislative_district)\n* us(fields)\n* state_zipcode(fields, state_fips, zip5)\n\nACS1 Geographies\n----------------\n\n* state(fields, state_fips)\n* state_congressional_district(fields, state_fips, district)\n* us(fields)\n\nSF1 Geographies\n---------------\n\n* state(fields, state_fips)\n* state_county(fields, state_fips, county_fips)\n* state_county_subdivision(fields, state_fips, county_fips, subdiv_fips)\n* state_county_tract(fields, state_fips, county_fips, tract)\n* state_place(fields, state_fips, place)\n* state_congressional_district(fields, state_fips, district)\n* state_msa(fields, state_fips, msa)\n* state_csa(fields, state_fips, csa)\n* state_district_place(fields, state_fips, district, place)\n* state_zipcode(fields, state_fips, zip5)\n\nPL Geographies\n--------------\n\n* state(fields, state_fips)\n* state_county(fields, state_fips, county_fips)\n* state_county_subdivision(fields, state_fips, county_fips, subdiv_fips)\n* state_county_tract(fields, state_fips, county_fips, tract)\n* state_county_blockgroup(fields, state_fips, county_fips, blockgroup)\n* state_place(fields, state_fips, place)\n* state_congressional_district(fields, state_fips, district)\n* state_legislative_district_upper(fields, state_fips, legislative_district)\n* state_legislative_district_lower(fields, state_fips, legislative_district)\n\nStates\n======\n\nThis package previously had a `census.states` module, but now uses the\n*us* package. ::\n\n    \u003e\u003e\u003e from us import states\n    \u003e\u003e\u003e print states.MD.fips\n    u'24'\n\nConvert FIPS to state abbreviation using `lookup()`: ::\n\n    \u003e\u003e\u003e print states.lookup('24').abbr\n    u'MD'\n\n\nBYOS - Bring Your Own Session\n=============================\n\nIf you'd prefer to use a custom configured requests.Session, you can pass it\nto the Census constructor::\n\n    s = requests.session()\n    s.headers.update({'User-Agent': 'census-demo/0.0'})\n\n    c = Census(\"MY_API_KEY\", session=s)\n\nYou can also replace the session used by a specific data set::\n\n    c.sf1.session = s\n\n\nExamples\n========\n\nThe geographic name for all census tracts for county 170 in Alaska::\n\n    c.sf1.get('NAME', geo={'for': 'tract:*',\n                           'in': 'state:{} county:170'.format(states.AK.fips)})\n\nThe same call using the `state_county_tract` convenience method::\n\n    c.sf1.state_county_tract('NAME', states.AK.fips, '170', Census.ALL)\n\nTotal number of males age 5 - 9 for all states::\n\n    c.acs5.get('B01001_004E', {'for': 'state:*'})\n\nThe same call using the state convenience method::\n\n    c.acs5.state('B01001_004E', Census.ALL)\n\nDon't know the list of tables in a survey, try this:\n\n    c.acs5.tables()\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatamade%2Fcensus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatamade%2Fcensus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatamade%2Fcensus/lists"}