BLSloadR is a packages designed to streamline access
to the time series database downloads from the U.S. Bureau of Labor
Statistics (https://www.bls.gov/), made available as flat files (https://download.bls.gov/pub/time.series/). It is
focused on accessing series that are frequently used by states to get
state-level estimates, but includes the load_bls_dataset()
function to provide generalized access to the other databases at this
website.
The primary functions in this package all begin with get_ and are listed below:
get_ces() - This accesses data from the Current
Employment Statistics (CES) program at the state and metropolitan area
levels. This provides employer-based estimates of employment, wages, and
hours worked. This is the “SM” database. For more information about
Current Employment Statistics, please visit https://www.bls.gov/ces/.
get_national_ces() - This accesses national data
from the CES program at the national level, which does not include
state-level breakouts. This is the “CE” database.
get_laus() - This accesses data from the Local Area
Unemployment Statistics (LAUS) program at a regional, state, and several
sub-state levels. This is a localized version of the Current Population
Survey (CPS) which is used to drive household-based estiamtes of
employment and unemployment. This is the “LA” database. Note that
because of the volume of data here, there are several different
geographies that may be specified to pull the appropriate data file from
BLS. For more information about Local Area Unemployment Statistics,
please visit https://www.bls.gov/lau/.
get_oews() - This access the Occupational Employment
and Wage Statistics (OEWS) data. This data provides survey-based
estimates of employmen and wages by occupation at state and sub-state
levels. This is the “OE” database. Note that only current-year data is
available for OEWS in this database, as it is not built as a time
series. For more information about Occupational Employment and Wage
Statistics, please visit https://www.bls.gov/oes/.
get_salt() - This data is not actually loated within
the time.series folder, but instead is sourced from https://www.bls.gov/lau/stalt.htm. These Alternative
Measures of Labor Underutilization for States are 12-month averages
built from CPS data which provide more expansive or restrictive
definitions of unemployment to measure the labor force, known as U1
through U6. This function also includes the optional geometry argument.
If set to TRUE, this will use tigris::states() and
tigris::shift_geometry() to provide state polygons for
convenient mapping of the output. For more information about the
Alternative Measures data, please visit https://www.bls.gov/lau/stalt.htm.
These functions download a series of files in the time.series database from BLS, join those files together, and then perform some simple filtering and streamlining to prepare the data for time series analysis. Generally speaking, these functions may be used with only the default parameters to get a table formatted and ready to be analyzed. To reduce the filtering and summaries performed by these functions, a series of arguments may beset to retain the data closer to its original format.
Within the functions to retrieve specific data sets there are a few common arguments which exist to simplify the results and minimize subsequent filtering.
transform = TRUE - This argument is used in
get_ces() and get_laus(). It is used to
convert the data as provided by BLS to numbers and ratios that are
easier to work with and manipulate. In particular is converts any ratios
and rates from a whole-number format to a decimal format. For example, a
labor for participation rate of 65.3% is represented in the BLS data as
65.3. Using transform = TRUE will convert this to 0.653 so
that it may be used as a ratio, or displayed as a percent format in R.
This argument will also convert numbers that are represented as “in
thousands” into whole numbers. For example, in the CES data, employment
of 1,234,500 is represented as 1234.5. While this conveys the
appropriate significant figures for the estimate, it can be inconvenient
to work with across programs. Using transform = TRUE will
change this to 1,234,500 and remove “in Thousands” from the data
description column.monthly_only = TRUE - This argument is used in
get_ces(), get_national_ces(), and
get_laus(). It removes annual data from the downloaded BLS
data, typically represented as period = "M13" to make the
data a more consistent time series.simplify_table = TRUE - This argument is used in
get_ces() and get_national_ces(). It is used
to remove some columns that are not commonly helpful in working with the
BLS data. For get_ces() these columns are
benchmark_year, begin_year,
begin_period, end_year, and
end_period which all describe the vintage of the data which
was downloaded. For get_national_ces() the columns are
series_title, begin_year,
begin_period, end_year,
end_period, naics_code,
publishing_status, display_level,
selectable, and sort_sequence. These columns
either contain codes with no explanation, provide duplicated but
inconsistently formatted information, or describe the vintage of the
data. For both functions, this argument also takes the year
and period columns, transforms them into a single date
column, and removes these two columns.This package relies on a custom function, fread_bls()
which aids in downloading and reading text files from the BLS.
Ordinarily, attempting to read files from the BLS directly from R will
return a 403 error, even though these files may be accessed easily from
a web browser. This package adds HTML headers to the GET requests to the
BLS web page to enable file downloads, checks the format of the files,
and reads in the contents. The functions above pull specific files from
the associated databases. The functions below, in contrast, are designed
to enable the user to
These optional helper functions can aid the user of this package by providing ways to summarize and explore all the time.series databases. The full list of databases as of November 2025 is listed at the end of this document.
bls_overview() - this function utilizes the standard
structure of the time.series databases, which has a simple text file
explaining the database structure that always follows the structure
id.txt where id is the two-character database
identification code. This function will render this summary file as a
simple HTML file.
load_bls_dataset() - this function attempts to read
and join all the relevant files in a BLS database, and will sometimes
prompt the user for additional input. For example, many databases have
multiple data files available (such as “AllItems” and “Current”) and may
have old series files as well (to manage historical coding changes).
Because these joins are performed automatically, the object returned by
this function is a more robust diagnostic object included the joined
data table as well as information about the joins. Use
Caution! BLS data structures are not always consistent. There
may be anomalies in the structure of individual databases, such as
missing column headers, that will degrade the ability of this function
to read the data.
Within each of the core functions is an argument that allows you to
receive more robust diagnostic information about the loading process.
setting return_diagnostics = TRUE will return a
bls_data_collection object, which can be used to get more information
about the loading process. For load_bls_dataset() you
should set return_full = TRUE.
This package was not created,endorsed, or maintained by the U.S. Bureau of Labor Statistics. It exists to make accessing that data easier and more streamlined using websites that are already publicly available.
The current list of databases in the time.series folder as of
November 2025 is listed below. Please note, not all series have current
data available. Additional information about a series may be gained by
running the bls_overview() function for a selected series,
such as bls_overview("ap").