pytidycensus.CensusAPI

class pytidycensus.CensusAPI(api_key=None, cache_dir=None)

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)

Initialize Census API client.

Parameters:

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

• cache_dir (Optional[str]) – 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)

Initialize Census API client.

Parameters:

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

• cache_dir (Optional[str]) – Directory for caching API responses. Defaults to user cache directory.

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

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 (Optional[str]) – Survey type (e.g., ‘acs5’, ‘acs1’)

• show_call (bool) – 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)

Get available geography codes for a dataset.

Parameters:

• year (int) – Census year

• dataset (str) – Dataset name

• survey (Optional[str]) – Survey type

Returns:

Available geography codes

Return type:

Dict[str, Any]

get_variables(year, dataset, survey=None)

Get available variables for a dataset.

Parameters:

• year (int) – Census year

• dataset (str) – Dataset name

• survey (Optional[str]) – Survey type

Returns:

Available variables with metadata

Return type:

Dict[str, Any]