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:
import pygris
ny_roads = pygris.roads(state = "NY", county = "New York")
ny_roads.plot()
Using the default year of 2024 Using FIPS code '36' for input 'NY' Using FIPS code '061' for input 'New York'
<Axes: >
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.
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 2024
Using FIPS code '26' for input 'MI' Using the default year of 2024 Using FIPS code '26' for input 'MI'
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 2024, 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-2024 |
divisions() |
cartographic (1:500k; 1:5m; 1:20m) | 2013-2024 |
regions() |
cartographic (1:500k; 1:5m; 1:20m) | 2013-2024 |
states() |
TIGER/Line; cartographic (1:500k; 1:5m; 1:20m) | 1990, 2000, 2010-2024 |
counties() |
TIGER/Line; cartographic (1:500k; 1:5m; 1:20m) | 1990, 2000, 2010-2024 |
tracts() |
TIGER/Line; cartographic (1:500k) | 1990, 2000, 2010-2024 |
block_groups() |
TIGER/Line; cartographic (1:500k) | 1990, 2000, 2010-2024 |
blocks() |
TIGER/Line | 2000, 2010-2024 |
places() |
TIGER/Line; cartographic (1:500k) | 2011-2024 |
pumas() |
TIGER/Line; cartographic (1:500k) | 2012-2024 |
school_districts() |
TIGER/Line; cartographic | 2011-2024 |
zctas() |
TIGER/Line; cartographic (1:500k) | 2000, 2010, 2012-2024 |
congressional_districts() |
TIGER/Line; cartographic (1:500k; 1:5m; 1:20m) | 2011-2024 |
state_legislative_districts() |
TIGER/Line; cartographic (1:500k) | 2011-2024 |
voting_districts() |
TIGER/Line; cartographic (1:500k) | 2012, 2020 |
area_water() |
TIGER/Line | 2011-2024 |
linear_water() |
TIGER/Line | 2011-2024 |
coastline |
TIGER/Line() | 2013-2024 |
core_based_statistical_areas() |
TIGER/Line; cartographic (1:500k; 1:5m; 1:20m) | 2011-2021, 2023-2024 |
combined_statistical_areas() |
TIGER/Line; cartographic (1:500k; 1:5m; 1:20m) | 2011-2024 |
metro_divisions() |
TIGER/Line | 2011-2024 |
new_england() |
TIGER/Line; cartographic (1:500k) | 2011-2022 |
county_subdivisions() |
TIGER/Line; cartographic (1:500k) | 2010-2024 |
urban_areas() |
TIGER/Line; cartographic (1:500k) | 2012-2024 |
primary_roads() |
TIGER/Line | 2011-2024 |
primary_secondary_roads() |
TIGER/Line | 2011-2024 |
roads() |
TIGER/Line | 2011-2024 |
rails() |
TIGER/Line | 2011-2024 |
native_areas() |
TIGER/Line; cartographic (1:500k) | 2011-2024 |
alaska_native_regional_corporations() |
TIGER/Line; cartographic (1:500k) | 2011-2024 |
tribal_block_groups() |
TIGER/Line | 2011-2024 |
tribal_census_tracts() |
TIGER/Line | 2011-2024 |
tribal_subdivisions_national() |
TIGER/Line | 2011-2024 |
landmarks() |
TIGER/Line | 2011-2024 |
military() |
TIGER/Line | 2011-2024 |