Basic usage of pygris¶

pygris functions work by downloading specific US Census Bureau shapefiles from the Census website which are then automatically loaded into a user's Python session as a GeoDataFrame. For a given dataset, the corresponding function is called with a state and county name (or FIPS code) as applicable.

For example, to retrieve roads for Manhattan (New York County), New York:

In [1]:

            
                Copied!
                
import pygris

ny_roads = pygris.roads(state = "NY", county = "New York")

ny_roads.plot()
import pygris

ny_roads = pygris.roads(state = "NY", county = "New York")

ny_roads.plot()

Using the default year of 2021
Using FIPS code '36' for input 'NY'
Using FIPS code '061' for input 'New York'

Out[1]:

<AxesSubplot: >

Data returned by pygris functions default to a geographic coordinate reference system of NAD 1983 (EPSG code 4269).

For many datasets available in pygris, users can either return data derived from the default TIGER/Line shapefiles or the Census Bureau's cartographic boundary shapefiles with the argument cb = True. Cartographic boundary shapefiles are clipped to the US shoreline and generalized in the interior for faster and improved cartographic display.

In [2]:

            
                Copied!
                
                    
                    
                
                

        
from pygris import counties
import matplotlib.pyplot as plt

# Get the default TIGER/Line file for counties in Michigan
mi_tiger = counties(state = "MI", cache = True)

# Get the cartographic boundary file with cb = True
mi_cartographic = counties(state = "MI", cb = True, cache = True)

# Plot the two side-by-side to compare them
fig, ax = plt.subplots(ncols = 2)
mi_tiger.plot(ax = ax[0])
mi_cartographic.plot(ax = ax[1])

ax[0].set_title("TIGER/Line")
ax[1].set_title("Cartographic")
from pygris import counties
import matplotlib.pyplot as plt

# Get the default TIGER/Line file for counties in Michigan
mi_tiger = counties(state = "MI", cache = True)

# Get the cartographic boundary file with cb = True
mi_cartographic = counties(state = "MI", cb = True, cache = True)

# Plot the two side-by-side to compare them
fig, ax = plt.subplots(ncols = 2)
mi_tiger.plot(ax = ax[0])
mi_cartographic.plot(ax = ax[1])

ax[0].set_title("TIGER/Line")
ax[1].set_title("Cartographic")

Using the default year of 2021
Using FIPS code '26' for input 'MI'
Using the default year of 2021
Using FIPS code '26' for input 'MI'

Out[2]:

Text(0.5, 1.0, 'Cartographic')

The above example uses the optional argument cache = True. If False (the default), pygris uses geopandas.read_file() to read the file directly from the Census Bureau website. If True, pygris will download the requested shapefile to a cache directory on the user's computer, and read the file from that cache directory when called again with the argument cache = True.

Available datasets in pygris¶

pygris functions currently default to a year of 2021, but this can be changed with the year argument for earlier or later years. Please note: cartographic boundary files in pygris are not available for 2011 and 2012.

Function	Datasets available	Years available
`nation()`	cartographic (1:5m; 1:20m)	2013-2022
`divisions()`	cartographic (1:500k; 1:5m; 1:20m)	2013-2022
`regions()`	cartographic (1:500k; 1:5m; 1:20m)	2013-2022
`states()`	TIGER/Line; cartographic (1:500k; 1:5m; 1:20m)	1990, 2000, 2010-2022
`counties()`	TIGER/Line; cartographic (1:500k; 1:5m; 1:20m)	1990, 2000, 2010-2022
`tracts()`	TIGER/Line; cartographic (1:500k)	1990, 2000, 2010-2022
`block_groups()`	TIGER/Line; cartographic (1:500k)	1990, 2000, 2010-2022
`blocks()`	TIGER/Line	2000, 2010-2022
`places()`	TIGER/Line; cartographic (1:500k)	2011-2022
`pumas()`	TIGER/Line; cartographic (1:500k)	2012-2022
`school_districts()`	TIGER/Line; cartographic	2011-2022
`zctas()`	TIGER/Line; cartographic (1:500k)	2000, 2010, 2012-2022
`congressional_districts()`	TIGER/Line; cartographic (1:500k; 1:5m; 1:20m)	2011-2022
`state_legislative_districts()`	TIGER/Line; cartographic (1:500k)	2011-2022
`voting_districts()`	TIGER/Line; cartographic (1:500k)	2012, 2020
`area_water()`	TIGER/Line	2011-2022
`linear_water()`	TIGER/Line	2011-2022
`coastline`	TIGER/Line()	2013-2022
`core_based_statistical_areas()`	TIGER/Line; cartographic (1:500k; 1:5m; 1:20m)	2011-2022
`combined_statistical_areas()`	TIGER/Line; cartographic (1:500k; 1:5m; 1:20m)	2011-2022
`metro_divisions()`	TIGER/Line	2011-2022
`new_england()`	TIGER/Line; cartographic (1:500k)	2011-2022
`county_subdivisions()`	TIGER/Line; cartographic (1:500k)	2010-2022
`urban_areas()`	TIGER/Line; cartographic (1:500k)	2012-2022
`primary_roads()`	TIGER/Line	2011-2022
`primary_secondary_roads()`	TIGER/Line	2011-2022
`roads()`	TIGER/Line	2011-2022
`rails()`	TIGER/Line	2011-2022
`native_areas()`	TIGER/Line; cartographic (1:500k)	2011-2022
`alaska_native_regional_corporations()`	TIGER/Line; cartographic (1:500k)	2011-2022
`tribal_block_groups()`	TIGER/Line	2011-2022
`tribal_census_tracts()`	TIGER/Line	2011-2022
`tribal_subdivisions_national()`	TIGER/Line	2011-2022
`landmarks()`	TIGER/Line	2011-2022
`military()`	TIGER/Line	2011-2022