get_ces: Download Current Employment Statistics (CES) Data

Description

This function downloads Current Employment Statistics data from the Bureau of Labor Statistics. The data includes national, regional, state, and substate employment statistics. By default, all available areas, data types, and periods are included.

Usage

get_ces(
  states = NULL,
  industry_filter = NULL,
  current_year_only = FALSE,
  transform = TRUE,
  monthly_only = TRUE,
  simplify_table = TRUE,
  suppress_warnings = TRUE,
  return_diagnostics = FALSE,
  cache = check_bls_cache_env()
)

Value

By default, returns a data.table with CES data. If return_diagnostics = TRUE, returns a bls_data_collection object containing data and comprehensive diagnostics.

Arguments

states: Character vector of state abbreviations to download (e.g., c("MA", "NY", "CA")). If specified, downloads only these states (all industries, all years). Cannot be combined with industry_filter or current_year_only. Use `list_ces_states()` to see all available states.
industry_filter: Character string specifying industry category to download. If specified, downloads this industry for all states (2007-present). Cannot be combined with states or current_year_only. Use `list_ces_industries()` to see all available industry filters.
current_year_only: Logical. If TRUE, downloads the current year file which contains all states and industries for recent years (2006-present). Cannot be combined with states or industry_filter. If FALSE (default), uses other parameters.
transform: Logical. If TRUE (default), converts employment values from thousands to actual counts by multiplying by 1000 for specific data types (codes 1, 6, 26) and removes ", In Thousands" from data type labels.
monthly_only: Logical. If TRUE (default), filters out annual data (period M13).
simplify_table: Logical. If TRUE (default), removes excess columns and creates a date column from Year and Period in the original data.
suppress_warnings: Logical. If TRUE (default), suppress individual download warnings and diagnostic messages for cleaner output during batch processing. If FALSE, returns the data and prints warnings and messages to the console.
return_diagnostics: Logical. If FALSE (default), returns only the data. If TRUE, returns the full bls_data_collection object with diagnostics.
cache: Logical. Uses USE_BLS_CACHE environment variable, or defaults to FALSE. If TRUE, will download a cached file from BLS server and update cache if BLS server indicates an updated file.

Details

**Performance Notes:** The default behavior downloads a very large file (~500MB+) containing all states and industries, which can take several minutes. For faster downloads, consider:

Use states = c("MA", "NY") to download only specific states
Use industry_filter = "total_nonfarm" for summary employment data only
Use current_year_only = TRUE for recent data only (2006-present)

**State Codes:** Use standard two-letter state abbreviations (e.g., "MA", "CA", "NY"). Puerto Rico = "PR", Virgin Islands = "VI", District of Columbia = "DC".

**Industry Filters:** Available options include:

"total_nonfarm" - Total non-farm employment summary
"total_private" - Private sector totals (2007-present)
"manufacturing" - Manufacturing sector (2007-present)
"construction" - Construction sector (2007-present)
"retail_trade" - Retail trade sector (2007-present)
"government" - Government sector (2007-present)
And others - see BLS documentation for full list

Examples

Run this code

# \donttest{
# Fast download: Massachusetts and Connecticut data only (all industries)
ces_states <- get_ces(states = c("MA", "CT"))

# Fast download: Manufacturing data for all states
ces_manufacturing <- get_ces(industry_filter = "manufacturing")

# Fast download: Current year data for all states and industries
ces_current <- get_ces(current_year_only = TRUE)

# Complete dataset (slower - all states, industries, and years)
ces_all <- get_ces()

# Download with full diagnostics if needed
ces_result <- get_ces(states = "MA", return_diagnostics = TRUE)
ces_data <- get_bls_data(ces_result)

# Check for download issues
if (has_bls_issues(ces_result)) {
  print_bls_warnings(ces_result)
}
# }