Skip to content
Download Census data and reformat it for humans
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
census_data_downloader Patch to employement status downloader Apr 15, 2019
data Patch to employement status downloader Apr 15, 2019
img Another chart Apr 2, 2019
.coveragerc Fixed coverage report. A little more data Apr 1, 2019
.gitignore Introduced a CLI Apr 3, 2019
.travis.yml More Mar 31, 2019
Pipfile.lock Introduced a CLI Apr 3, 2019 A couple more downloaders Apr 2, 2019
setup.cfg More Mar 31, 2019 v0.0.4 Apr 5, 2019 first pass at allowing different crosswalks based on the year Apr 5, 2019


Download Census data and reformat it for humans.


$ pipenv install census-data-downloader


There's now a command-line tool named censusdatadownloader ready for you.

Usage: censusdatadownloader [OPTIONS] TABLE COMMAND [ARGS]...

  Download Census data and reformat it for humans

  --data-dir TEXT  The folder where you want to download the data
  --year INTEGER   The years of data to download. By default it gets only the
                   latest year. Submit 'all' to get every year.
  --force          Force the downloading of the data
  --help           Show this message and exit.

  congressionaldistricts     Download Congressional districts
  counties                   Download counties in all states
  everything                 Download everything from everywhere
  nationwide                 Download nationwide data
  places                     Download Census-designated places
  statelegislativedistricts  Download statehouse districts in provided state
  states                     Download states
  tracts                     Download Census tracts in provided state
  usa                        Download all datasets that cover full USA

Before you can use it you will need to add your CENSUS_API_KEY to your environment. Here's one quick way to do that:

$ export CENSUS_API_KEY='<your API key>'

Using it is as simple as providing one our processed table names to one of the download subcommands.

Here's an example of downloading all state-level data from the medianage dataset.

$ censusdatadownloader medianage states

You can specify the download directory with --data-dir.

$ censusdatadownloader --data-dir ./my-special-folder/ medianage states

And you can change the year you download with --year.

$ censusdatadownloader --year 2010 medianage states

That's it. Mix and match tables and subcommands to get whatever you need.

Adding support for a new table

Subclass our downloader and provided it with its required inputs.

import collections
from .base import BaseDownloader
from .registry import register_downloader

class MedianHouseholdIncomeDownloader(BaseDownloader):
    PROCESSED_TABLE_NAME = "medianhouseholdincome"  # Your humanized table name
    RAW_TABLE_NAME = 'B19013'  # The id of the source table
    RAW_FIELD_CROSSWALK = collections.OrderedDict({
        # A crosswalk between the raw field name and our humanized field name.
        "001E": "median"

Now you can import and run it yourself.

>>> from yourmodule import MedianHouseholdIncomeDownloader
>>> obj = MedianHouseholdIncomeDownloader("<YOUR CENSUS API KEY>", data_dir="./your-data-folder/")
>>> obj.download_everything()

That's it. If you make some good ones, please consider submitting them as pull requests so everyone can benefit.

Working with the data

All of the data files processed by this repository are published in the processed data folder. They can be called in to applications via their raw URLs. Here are some examples created using Observable.

Here's county-level race data in a bivariate map of black and Latino populations.

Black and Latino U.S. population shares

Now a stacked bar using the state-level version of the race dataset.

Racial makeup  of U.S. states and territories

Median age by state can take a totally different form.

Median age by gender

Datasets can be easily combined using the Census Bureau's geoid field. Here's education and income by county in a scatterplot with hexagonal bins.

Education and income in U.S. counties

Lace a few more county-level datasets in and you can make parallel coordinates charts.

The demographics and destiny of all 3,220 U.S. counties

You can’t perform that action at this time.