pytidycensus.CensusAPI

class pytidycensus.CensusAPI(api_key=None, cache_dir=None)[source]

Bases: object

Core client for interacting with US Census Bureau APIs.

Handles authentication, rate limiting, caching, and error handling for Census API requests.

__init__(api_key=None, cache_dir=None)[source]

Initialize Census API client.

Parameters:

  • api_key (str, optional) – Census API key. If not provided, will look for CENSUS_API_KEY environment variable.

  • cache_dir (str, optional) – Directory for caching API responses. Defaults to user cache directory.

Methods

__init__([api_key, cache_dir])

Initialize Census API client.

get(year, dataset, variables, geography[, ...])

Make a request to the Census API.

get_geography_codes(year, dataset[, survey])

Get available geography codes for a dataset.

get_variables(year, dataset[, survey])

Get available variables for a dataset.

Attributes

BASE_URL

BASE_URL = 'https://api.census.gov/data'
__init__(api_key=None, cache_dir=None)[source]

Initialize Census API client.

Parameters:

  • api_key (str, optional) – Census API key. If not provided, will look for CENSUS_API_KEY environment variable.

  • cache_dir (str, optional) – Directory for caching API responses. Defaults to user cache directory.

get(year, dataset, variables, geography, survey=None, show_call=False)[source]

Make a request to the Census API.

Parameters:

  • year (int) – Census year

  • dataset (str) – Dataset name (e.g., ‘acs’, ‘dec’)

  • variables (List[str]) – List of variable codes to retrieve

  • geography (Dict[str, str]) – Geography specification (e.g., {‘for’: ‘county:*’, ‘in’: ‘state:06’})

  • survey (str, optional) – Survey type (e.g., ‘acs5’, ‘acs1’)

  • show_call (bool, default False) – Whether to print the API call URL

Returns:

Parsed JSON response from API

Return type:

List[Dict[str, Any]]

Raises:

  • requests.RequestException – If API request fails

  • ValueError – If API returns error response

get_geography_codes(year, dataset, survey=None)[source]

Get available geography codes for a dataset.

Parameters:

  • year (int) – Census year

  • dataset (str) – Dataset name

  • survey (str, optional) – Survey type

Returns:

Available geography codes

Return type:

Dict[str, Any]

get_variables(year, dataset, survey=None)[source]

Get available variables for a dataset.

Parameters:

  • year (int) – Census year

  • dataset (str) – Dataset name

  • survey (str, optional) – Survey type

Returns:

Available variables with metadata

Return type:

Dict[str, Any]