pytidycensus.api

Core Census API client for making requests to the US Census Bureau APIs.

Functions

set_census_api_key(api_key)

Set Census API key as environment variable.

Classes

CensusAPI([api_key, cache_dir])

Core client for interacting with US Census Bureau APIs.

class pytidycensus.api.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.

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]

pytidycensus.api.set_census_api_key(api_key)

Set Census API key as environment variable.

Parameters:

api_key (str) – Census API key obtained from https://api.census.gov/data/key_signup.html

Raises:

ValueError – If the API key is not a string of exactly 40 characters

Return type:

None