{"id":13567037,"url":"https://github.com/datadesk/census-data-downloader","last_synced_at":"2025-10-06T20:09:07.636Z","repository":{"id":34415791,"uuid":"178750724","full_name":"datadesk/census-data-downloader","owner":"datadesk","description":"Download U.S. census data and reformat it for humans","archived":false,"fork":false,"pushed_at":"2024-09-30T17:40:14.000Z","size":873308,"stargazers_count":224,"open_issues_count":30,"forks_count":37,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-09-25T15:11:01.095Z","etag":null,"topics":["api-wrapper","census","data-journalism","demographics","journalism","mapping-la-pipeline","news","pandas","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datadesk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-31T22:48:45.000Z","updated_at":"2025-09-01T00:26:02.000Z","dependencies_parsed_at":"2024-06-21T16:35:05.433Z","dependency_job_id":"77e39e3d-c841-4a34-8084-a62422862a58","html_url":"https://github.com/datadesk/census-data-downloader","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/datadesk/census-data-downloader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datadesk%2Fcensus-data-downloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datadesk%2Fcensus-data-downloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datadesk%2Fcensus-data-downloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datadesk%2Fcensus-data-downloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datadesk","download_url":"https://codeload.github.com/datadesk/census-data-downloader/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datadesk%2Fcensus-data-downloader/sbom","scorecard":{"id":324353,"data":{"date":"2025-08-11","repo":{"name":"github.com/datadesk/census-data-downloader","commit":"5e75334f47e2226129e6dafb622b3952ccb5174c"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.6,"checks":[{"name":"Code-Review","score":1,"reason":"Found 2/19 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/continuous-deployment.yaml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:46: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:50: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:78: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:82: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:114: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:128: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:135: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/continuous-deployment.yaml:142: update your workflow using https://app.stepsecurity.io/secureworkflow/datadesk/census-data-downloader/continuous-deployment.yaml/master?enable=pin","Warn: downloadThenRun not pinned by hash: .github/workflows/continuous-deployment.yaml:26","Warn: downloadThenRun not pinned by hash: .github/workflows/continuous-deployment.yaml:58","Warn: downloadThenRun not pinned by hash: .github/workflows/continuous-deployment.yaml:90","Info:   0 out of   9 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned","Info:   0 out of   3 downloadThenRun dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 13 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"30 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-230 / GHSA-248v-346w-9cwc","Warn: Project is vulnerable to: PYSEC-2024-60 / GHSA-jjg7-2v4v-x38h","Warn: Project is vulnerable to: GHSA-cpwx-vrp4-4pq7","Warn: Project is vulnerable to: GHSA-gmj6-6f8f-6699","Warn: Project is vulnerable to: GHSA-h5c8-rqwp-cp95","Warn: Project is vulnerable to: GHSA-h75v-3vvj-5mfj","Warn: Project is vulnerable to: GHSA-q2x7-8rv6-6q7h","Warn: Project is vulnerable to: GHSA-33p9-3p43-82vq","Warn: Project is vulnerable to: GHSA-4qhp-652w-c22x","Warn: Project is vulnerable to: PYSEC-2023-157 / GHSA-64x5-55rw-9974","Warn: Project is vulnerable to: PYSEC-2023-272 / GHSA-h56g-gq9v-vc8r","Warn: Project is vulnerable to: PYSEC-2024-165 / GHSA-hrw6-wg82-cm62","Warn: Project is vulnerable to: PYSEC-2023-155 / GHSA-r726-vmfq-j9j3","Warn: Project is vulnerable to: GHSA-44cc-43rp-5947","Warn: Project is vulnerable to: GHSA-4m77-cmpx-vjc4","Warn: Project is vulnerable to: GHSA-9q39-rmj3-p4r2","Warn: Project is vulnerable to: GHSA-9hjg-9r4m-mvj7","Warn: Project is vulnerable to: GHSA-9wx4-h78v-vm56","Warn: Project is vulnerable to: PYSEC-2025-49 / GHSA-5rjg-fvgr-3xxf","Warn: Project is vulnerable to: GHSA-cx63-2mw6-8hw5","Warn: Project is vulnerable to: GHSA-753j-mpmx-qq6g","Warn: Project is vulnerable to: GHSA-7cx3-6m66-7c5m","Warn: Project is vulnerable to: GHSA-8w49-h785-mj3c","Warn: Project is vulnerable to: GHSA-qppv-j76h-2rpx","Warn: Project is vulnerable to: GHSA-w235-7p84-xx57","Warn: Project is vulnerable to: GHSA-34jh-p97f-mpxf","Warn: Project is vulnerable to: PYSEC-2023-212 / GHSA-g4mx-q9vg-27p4","Warn: Project is vulnerable to: GHSA-pq67-6m6q-mj2v","Warn: Project is vulnerable to: PYSEC-2023-192 / GHSA-v845-jxx5-vc9f","Warn: Project is vulnerable to: GHSA-jfmj-5v4g-7637"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-18T02:06:52.003Z","repository_id":34415791,"created_at":"2025-08-18T02:06:52.003Z","updated_at":"2025-08-18T02:06:52.003Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278671745,"owners_count":26025745,"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","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["api-wrapper","census","data-journalism","demographics","journalism","mapping-la-pipeline","news","pandas","python"],"created_at":"2024-08-01T13:02:22.137Z","updated_at":"2025-10-06T20:09:07.573Z","avatar_url":"https://github.com/datadesk.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# census-data-downloader\n\nDownload [American Community Survey data](https://www.census.gov/programs-surveys/acs/data.html) from the U.S. Census Bureau and reformat it for humans.\n\n## What's available\n\nAll of the data files processed by this repository are published in the [`data/processed/`](./data/processed/) folder. They can be called in to applications via their raw URLs, like https://raw.githubusercontent.com/datadesk/census-data-downloader/master/data/processed/acs5_2017_population_counties.csv\n\n## The command-line interface\n\nThe library can be installed as a command-line interface that lets you download files on demand.\n\n### Installation\n\n```bash\n$ pipenv install census-data-downloader\n```\n\n### Command-line usage\n\nThere's now a tool named `censusdatadownloader` ready for you.\n\n```bash\nUsage: censusdatadownloader [OPTIONS] TABLE COMMAND [ARGS]...\n\n  Download Census data and reformat it for humans\n\nOptions:\n  --data-dir TEXT  The folder where you want to download the data\n  --year [2009-2022]   The years of data to download. By default it gets only the\n                   latest year. Not all data are available for every year. Submit 'all' to get every year.\n  --force          Force the downloading of the data\n  --help           Show this message and exit.\n\nCommands:\n  aiannhhomelands            Download American Indian, Alaska Native and...\n  cnectas                    Download combined New England city and town...\n  congressionaldistricts     Download Congressional districts\n  counties                   Download counties in all states\n  countysubdivision          Download county subdivisions\n  csas                       Download combined statistical areas\n  divisions                  Download divisions\n  elementaryschooldistricts  Download elementary school districts\n  everything                 Download everything from everywhere\n  msas                       Download metropolitian statistical areas\n  nationwide                 Download nationwide data\n  nectas                     Download New England city and town areas\n  places                     Download Census-designated places\n  pumas                      Download public use microdata areas\n  regions                    Download regions\n  secondaryschooldistricts   Download secondary school districts\n  statelegislativedistricts  Download statehouse districts\n  states                     Download states\n  tracts                     Download Census tracts\n  unifiedschooldistricts     Download unified school districts\n  urbanareas                 Download urban areas\n  zctas                      Download ZIP Code tabulation areas\n```\n\nBefore you can use it you will need to add your CENSUS_API_KEY to your environment. If you don't have an API key, you can go [here.](https://api.census.gov/data/key_signup.html) One quick way to add your key:\n\n```bash\n$ export CENSUS_API_KEY='\u003cyour API key\u003e'\n```\n\nUsing it is as simple as providing one our processed table names to one of the download subcommands.\n\nHere's an example of downloading all state-level data from the `medianage` dataset.\n\n```bash\n$ censusdatadownloader medianage states\n```\n\nYou can specify the download directory with `--data-dir`.\n\n```bash\n$ censusdatadownloader --data-dir ./my-special-folder/ medianage states\n```\n\nAnd you can change the year you download with `--year`.\n\n```bash\n$ censusdatadownloader --year 2010 medianage states\n```\n\nThat's it. Mix and match tables and subcommands to get whatever you need.\n\n### Python usage\n\nYou can also download tables from Python scripts. Import the class of the [processed table](https://github.com/datadesk/census-data-downloader/tree/master/census_data_downloader/tables) you wish to retrieve and pass in your API key. Then call one of the download methods.\n\nThis example brings in all state-level data from the medianhouseholdincomeblack dataset.\n\n```python\n\u003e\u003e\u003e from census_data_downloader.tables import MedianHouseholdIncomeBlackDownloader\n\u003e\u003e\u003e downloader = MedianHouseholdIncomeBlackDownloader('\u003cYOUR KEY\u003e')\n\u003e\u003e\u003e downloader.download_states()\n```\n\nYou can specify the data directory and the years by passing in the `data_dir` and `years` keyword arguments.\n\n```python\n\u003e\u003e\u003e downloader = MedianHouseholdIncomeBlackDownloader('\u003cYOUR KEY\u003e', data_dir='./', years=2016)\n\u003e\u003e\u003e downloader.download_states()\n```\n\n### Usage examples\n\nA gallery of graphics powered by our data is available on [Observable](https://observablehq.com/collection/@datadesk/u-s-census-data).\n\n[![Black and Latino U.S. population shares](./img/race-map.png)](https://observablehq.com/collection/@datadesk/u-s-census-data)\n\nThe Los Angeles Times used this library for [an analysis of Census undercounts](https://www.latimes.com/projects/la-na-census-native-americans-navajo-nation/) on Native American reservations. The code that powers it is available as an [open-source computational notebook](https://github.com/datadesk/native-american-census-analysis).\n\n[![The 2020 census is coming. Will Native Americans be counted?](./img/latimes-native-american-undercount.png)](https://www.latimes.com/projects/la-na-census-native-americans-navajo-nation/)\n\n## Contributing to the library\n\n### Adding support for a new table\n\nSubclass our downloader and provided it with its required inputs.\n\n```python\nimport collections\nfrom census_data_downloader.core.tables import BaseTableConfig\nfrom census_data_downloader.core.decorators import register\n\n\n@register\nclass MedianHouseholdIncomeDownloader(BaseTableConfig):\n    PROCESSED_TABLE_NAME = \"medianhouseholdincome\"  # Your humanized table name\n    UNIVERSE = \"households\"  # The universe value for this table\n    RAW_TABLE_NAME = 'B19013'  # The id of the source table\n    RAW_FIELD_CROSSWALK = collections.OrderedDict({\n        # A crosswalk between the raw field name and our humanized field name.\n        \"001\": \"median\"\n    })\n```\n\nAdd it to the imports in the [`__init__.py`](census_data_downloader/tables/__init__.py) file and it's good to go.\n\n### Developing the CLI\n\nThe command-line interface is implemented using Click and setuptools. To install it locally for development inside your virtual environment, run the following installation command, as [prescribed by the Click documentation](https://click.palletsprojects.com/en/7.x/setuptools/#setuptools-integration).\n\n```bash\n$ pip install --editable .\n```\n\nThat's it. If you make some good ones, please consider submitting them as pull requests so everyone can benefit.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadesk%2Fcensus-data-downloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatadesk%2Fcensus-data-downloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadesk%2Fcensus-data-downloader/lists"}