Skip to contents

Get QCEW Data Slices

get_qcew.Rd

This function pulls data from the BLS QCEW Open Data Access CSV Data Slices. It iterates over specified years and quarters (or annual data) to retrieve industry-specific or area-specific data tables and merges them into a single data.table. Optionally, it joins internal package lookup tables for industry and area descriptions.

Usage

get_qcew(
  period_type = "quarter",
  year_start = NULL,
  year_end = NULL,
  industry_code = NULL,
  area_code = NULL,
  add_lookups = TRUE,
  silently = FALSE
)

Arguments

period_type

Character. Either "quarter" or "year". Defaults to "quarter".

year_start

Numeric. The first year to retrieve data for. Defaults to the year of the date 6 months prior to the current system date.

year_end

Numeric. The last year to retrieve data for. Defaults to the year of the date 6 months prior to the current system date.

industry_code

Character. The NAICS industry code (e.g., "10", "31-33"). Constructs a URL for an Industry Data Slice. Mutually exclusive with `area_code`.

area_code

Character. The QCEW area code (e.g., "US000", "32000", "C2982"). Constructs a URL for an Area Data Slice. Mutually exclusive with `industry_code`.

add_lookups

Logical. If TRUE, joins the package's ind_lookup and area_lookup tables to the results to provide descriptive labels. Defaults to TRUE.

silently

Logical. If TRUE, suppresses status messages about the URLs being accessed. Defaults to FALSE.

Value

A combined data.table containing the requested QCEW data, optionally merged with lookup columns and a calculated date column. The data layout is different for quarterly or annual data files set by the `period_type` argument.

For Quarterly files:

  • area_fips - Character. Area code of row. Included `area_lookup` data file contains mapping information.

  • industry_code - Character. NAICS, Supersector, Cluster, or Total All Industries code. Numeric characters as a string to preserve examining the structure heirarchy.

  • own_code - Integer. Values of 0-5 to designate ownership. See definitions at https://www.bls.gov/cew/classifications/ownerships/ownership-titles.htm

  • agglvl_code - Integer. Two digit code identifying the level of aggregation. See definitons at https://www.bls.gov/cew/classifications/aggregation/agg-level-titles.htm

  • size_code - Integer. Single-digit code representing the size of establishments. See definitions at https://www.bls.gov/cew/classifications/size/size-titles.htm

  • year Integer. Four-digit calendar year for the returned data.

  • qtr Integer. The calendar quarter of the data.

  • disclosure_code Character. Values are either a blank string on "N". Values of N do not disclose employment or wages to maintain confidentiality.

  • qtryly_estabs Integer. The number of business establishments (worksites) for the industry in the area in the quarter.

  • month1_emplvl Integer. Employment in the first month of the quarter (January, April, July, or October).

  • month2_emplvl Integer. Employment in the second month of the quarter (February, May, August, November).

  • month3_emplvl Integer. Employment in the third month of the quarter (March, June, September, December).

  • total_qtrly_wages Ingeger64. Total wages paid during the quarter.

  • taxable_qtrly_wages Ingeger64. Wages subject to unemployment insurance (UI) taxes during the quarter. Note - wages subject to UI vary by state and will follow different seasonal patterns as a result.

  • qtrly_contributions Integer. UI taxes (Contributions) paid by employers for this quarter. Note - UI tax policy varies by state.

  • avg_wkly_wage Integer. Average weekly wage during the quarter (Total wages divided by average employment, divided by 13).

  • lq_disclosure_code Character. Blank or "N". Values of "N" will suppress location quotient data for confidentiality.

  • lq_qtrly_estabs Numeric. Location quotient of establishments relative to the U.S.

  • lq_month1_emplvl Numeric. Location quotient of month 1 employment relative to the U.S.

  • lq_month2_emplvl Numeric. Location quotient of month 2 employment relative to the U.S.

  • lq_month3_emplvl Numeric. Location quotient of month 3 employment relative to the U.S.

  • lq_total_qtrly_wages Numeric. Location quotient of total wages relative to the U.S.

  • lq_taxable_qtrly_wages Numeric. Location quotient of taxable quarterly wages relative to the U.S.

  • lq_qtrly_contributions Numeric. Location quotient of quarterly UI taxes paid relative to the U.S.

  • lq_avg_wkly_wage Numeric. Location quotient of average weekly wages relative to the U.S.

  • oty_disclosure_code Character. Blank or "N". Values of "N" will suppress over-the-year data for confidentiality.

  • oty_qtrly_estabs_chg Numeric. Over-the-year change in establishments.

  • oty_qtrly_estabs_pct_chg Numeric. Over-the-year percent change in establishments.

  • oty_month1_emplvl_chg Numeric. Over-the-year change in month 1 employment.

  • oty_month1_emplvl_pct_chg Numeric. Over-the-year percent change in month 1 employment.

  • oty_month2_emplvl_chg Numeric. Over-the-year change in month 2 employment.

  • oty_month2_emplvl_pct_chg Numeric. Over-the-year percent change in month 2 employment.

  • oty_month3_emplvl_chg Numeric. Over-the-year change in month 3 employment.

  • oty_month3_emplvl_pct_chg Numeric. Over-the-year percent change in month 3 employment.

  • oty_total_qtrly_wages_chg Numeric. Over-the-year change in total wages.

  • oty_total_qtrly_wages_pct_chg Numeric. Over-the-year percent change in total wages.

  • oty_taxable_qtrly_wages_chg Numeric. Over-the-year change in taxable quarterly wages.

  • oty_taxable_qtrly_wages_pct_chg Numeric. Over-the-year percent change in taxable quarterly wages.

  • oty_qtrly_contributions_chg Numeric. Over-the-year change in quarterly UI taxes paid.

  • oty_qtrly_contributions_pct_chg Numeric. Over-the-year percent change in quarterly UI taxes paid.

  • oty_avg_wkly_wage_chg Numeric. Over-the-year change in average weekly wages.

  • oty_avg_wkly_wage_pct_chg Numeric. Over-the-year percent change in average weekly wages.

  • date Date. Calculated calendar date based on year and quarter. Reflects first day of the quarter.

  • industry_title Character. Added based on industry_code

  • ind_level Character. Description of the level of aggregation based on the industry_code.

  • naics_2d Character. First two characters in the industry_code, useful for identifying industries.

  • sector Character. Similar to naics_2d, but for industries like Manufacturing which have multiple two digit NAICS codes, this will span those groupings, for example "31-33"

  • vintage_start. Integer. Calendar year of the earliest vintage for this industry_code. NAICS codes are updated every 5 years. When using this industry codes from before this date, these titles may not exist or may be incorrect.

  • vintage_end. Integer. Calendar year of the last year this industry code was used. Years after this point should not contain this industry code. Set to 3000 for current data.

  • area_title Character. Area description based on area_fips as provided by the BLS.

  • area_type Character. Description of the type of area based on the area_title. More consistent naming and grouping than BLS data.

  • stfips Character. The two-digit FIPS code of the state containing a given area. Set to "00" for multi-state regions.

  • specified_region. Either a two-character US Postal Service abbreviation for the state containing an area or a hyphenated list of such codes for multi-state areas.

For Annual files:

  • area_fips - Character. Area code of row. Included `area_lookup` data file contains mapping information.

  • industry_code - Character. NAICS, Supersector, Cluster, or Total All Industries code. Numeric characters as a string to preserve examining the structure heirarchy.

  • own_code - Integer. Values of 0-5 to designate ownership. See definitions at https://www.bls.gov/cew/classifications/ownerships/ownership-titles.htm

  • agglvl_code - Integer. Two digit code identifying the level of aggregation. See definitons at https://www.bls.gov/cew/classifications/aggregation/agg-level-titles.htm

  • size_code - Integer. Single-digit code representing the size of establishments. See definitions at https://www.bls.gov/cew/classifications/size/size-titles.htm

  • year Integer. Four-digit calendar year for the returned data.

  • qtr Character. Set to "A" to represent annual data.

  • disclosure_code Character. Values are either a blank string on "N". Values of N do not disclose employment or wages to maintain confidentiality.

  • annual_avg_estabs Integer. The average number of business establishments (worksites) for the industry in the area for the year.

  • annual_avg_emplvl Integer. The average monthly employment level in a given year.

  • total_annual_wages Ingeger64. Total wages paid during the year.

  • taxable_annual_wages Ingeger64. Wages subject to unemployment insurance (UI) taxes during the year. Note - wages subject to UI vary by state and will follow different seasonal patterns as a result.

  • annual_contributions Integer. UI taxes (Contributions) paid by employers for this year. Note - UI tax policy varies by state.

  • annual_avg_wkly_wage Integer. Average weekly wage during the year (Total wages divided by average employment, divided by 52).

  • avg_annual_pay Integer. Average annual pay during the year.

  • lq_disclosure_code Character. Blank or "N". Values of "N" will suppress location quotient data for confidentiality.

  • lq_annual_avg_estabs Numeric. Location quotient of establishments relative to the U.S.

  • lq_annual_avg_emplvl Numeric. Location quotient of annual employment relative to the U.S.

  • lq_total_annual_wages Numeric. Location quotient of total wages relative to the U.S.

  • lq_taxable_annual_wages Numeric. Location quotient of taxable annual wages relative to the U.S.

  • lq_annual_contributions Numeric. Location quotient of annual UI taxes paid relative to the U.S.

  • lq_annual_avg_wkly_wage Numeric. Location quotient of average weekly wages relative to the U.S.

  • lq_avg_annual_pay Numeric. Location quotient of average annual pay relative to the U.S.

  • oty_disclosure_code Character. Blank or "N". Values of "N" will suppress over-the-year data for confidentiality.

  • oty_annual_avg_estabs_chg Integer. Over-the-year change in establishments.

  • oty_annual_avg_estabs_pct_chg Numeric. Over-the-year percent change in establishments.

  • oty_annual_avg_emplvl_chg Integer. Over-the-year change in average annual employment.

  • oty_annual_avg_emplvl_pct_chg Numeric. Over-the-year percent change in average annual employment.

  • oty_total_annual_wages_chg Integer. Over-the-year change in total wages.

  • oty_total_annual_wages_pct_chg Numeric. Over-the-year percent change in total wages.

  • oty_taxable_annual_wages_chg Integer. Over-the-year change in taxable annual wages.

  • oty_taxable_annual_wages_pct_chg Numeric. Over-the-year percent change in taxable annual wages.

  • oty_annual_contributions_chg Integer. Over-the-year change in annual UI taxes paid.

  • oty_annual_contributions_pct_chg Numeric. Over-the-year percent change in annual UI taxes paid.

  • oty_annual_avg_wkly_wage_chg Integer. Over-the-year change in average weekly wages.

  • oty_annual_avg_wkly_wage_pct_chg Numeric. Over-the-year percent change in average weekly wages.

  • oty_avg_annual_pay_chg Integer. Over-the-year change in average annual pay.

  • oty_avg_annual_pay_pct_chg Numeric. Over-the-year percent change in average annual pay.

  • date Date. Calculated calendar date based on year and quarter. Reflects first day of the quarter.

  • industry_title Character. Added based on industry_code

  • ind_level Character. Description of the level of aggregation based on the industry_code.

  • naics_2d Character. First two characters in the industry_code, useful for identifying industries.

  • sector Character. Similar to naics_2d, but for industries like Manufacturing which have multiple two digit NAICS codes, this will span those groupings, for example "31-33"

  • vintage_start. Integer. Calendar year of the earliest vintage for this industry_code. NAICS codes are updated every 5 years. When using this industry codes from before this date, these titles may not exist or may be incorrect.

  • vintage_end. Integer. Calendar year of the last year this industry code was used. Years after this point should not contain this industry code. Set to 3000 for current data.

  • area_title Character. Area description based on area_fips as provided by the BLS.

  • area_type Character. Description of the type of area based on the area_title. More consistent naming and grouping than BLS data.

  • stfips Character. The two-digit FIPS code of the state containing a given area. Set to "00" for multi-state regions.

  • specified_region. Either a two-character US Postal Service abbreviation for the state containing an area or a hyphenated list of such codes for multi-state areas.

Examples

# \donttest{
# Get quarterly data for "Total, all industries" (Code 10)
# Includes industry/area descriptions and a date column by default
dt_default <- get_qcew(industry_code = "10")
#> Accessing: https://data.bls.gov/cew/data/api/2025/1/industry/10.csv
#> Warning: Some columns are type 'integer64' but package bit64 is not installed. Those columns will print as strange looking floating point data. There is no need to reload the data. Simply install.packages('bit64') to obtain the integer64 print method and print the data again.
#> Accessing: https://data.bls.gov/cew/data/api/2025/2/industry/10.csv
#> Warning: cannot open URL 'https://data.bls.gov/cew/data/api/2025/2/industry/10.csv': HTTP status was '404 Not Found'
#> Warning: Could not fetch data for: https://data.bls.gov/cew/data/api/2025/2/industry/10.csv - cannot open URL 'https://data.bls.gov/cew/data/api/2025/2/industry/10.csv'
#> Accessing: https://data.bls.gov/cew/data/api/2025/3/industry/10.csv
#> Warning: cannot open URL 'https://data.bls.gov/cew/data/api/2025/3/industry/10.csv': HTTP status was '404 Not Found'
#> Warning: Could not fetch data for: https://data.bls.gov/cew/data/api/2025/3/industry/10.csv - cannot open URL 'https://data.bls.gov/cew/data/api/2025/3/industry/10.csv'
#> Accessing: https://data.bls.gov/cew/data/api/2025/4/industry/10.csv
#> Warning: cannot open URL 'https://data.bls.gov/cew/data/api/2025/4/industry/10.csv': HTTP status was '404 Not Found'
#> Warning: Could not fetch data for: https://data.bls.gov/cew/data/api/2025/4/industry/10.csv - cannot open URL 'https://data.bls.gov/cew/data/api/2025/4/industry/10.csv'

# Get annual data for Nevada (Code 32000) for 2023 without lookups or messages
dt_year <- get_qcew(period_type = "year",
                    year_start = 2023,
                    year_end = 2023,
                    area_code = "32000",
                    add_lookups = FALSE,
                    silently = TRUE)
#> Warning: Some columns are type 'integer64' but package bit64 is not installed. Those columns will print as strange looking floating point data. There is no need to reload the data. Simply install.packages('bit64') to obtain the integer64 print method and print the data again.
# }