blsAPI — U.S. Bureau of Labor Statistics Data for R

blsAPI is an R package that allows users to request data for one or multiple series through the U.S. Bureau of Labor Statistics (BLS) Application Programming Interface (API). The BLS API gives the public access to economic data from all BLS programs.

Quick Tour

Installation

blsAPI can be installed easily through CRAN or GitHub.

CRAN

install.packages('blsAPI')

GitHub

library(devtools)
install_github('mikeasilva/blsAPI')

API Basics

The blsAPI package supports two versions of the BLS API. API Version 2.0 requires registration and offers greater query limits. It also allows users to request net and percent changes and series description information. See below for more details.

Service	Version 2.0 (Registered)	Version 1.0 (Unregistered)
Daily query limit	500	25
Series per query limit	50	25
Years per query limit	20	10
Net/Percent Changes	Yes	No
Optional annual averages	Yes	No
Series description information (catalog)	Yes	No

Sample Code

Example 1

The following example will retrieve the civilian unadjusted Employment Cost Index (ECI) via the API and process the request into a data frame.

library(rjson)
library(blsAPI)

response <- blsAPI('CIU1010000000000A')
json     <- fromJSON(response)

data_list  <- json$Results$series[[1]]$data[-1]
cpi        <- data.frame(matrix(unlist(data_list), ncol = 4, byrow = TRUE, 
                          dimnames = list(NULL, c("year", "period", 
                                                  "periodName", "value"))), 
                                                   stringsAsFactors = FALSE)
cpi

The resulting data frame looks like this (Note: Your results may look different depending on when you pull the data):

year	period	periodName	value
2014	Q03	3rd Quarter	2.2
2014	Q02	2nd Quarter	2.0
2014	Q01	1st Quarter	1.8
2013	Q04	4th Quarter	2.0
2013	Q03	3rd Quarter	1.9
2013	Q02	2nd Quarter	1.9
2013	Q01	1st Quarter	1.9
2012	Q04	4th Quarter	1.9
2012	Q03	3rd Quarter	1.9
2012	Q02	2nd Quarter	1.7
2012	Q01	1st Quarter	1.9

Example 2

This example pulls monthly unemployment and labor force estimates for Manhattan (New York County, NY) using the version 2.0 API. We graph a calculated unemployment rate including shading for the Great Recession. According the National Bureau of Economic Research (NBER) the Great Recession ran from December 2007 to June 2009.

library(rjson)
library(blsAPI)
library(ggplot2)

## Pull the data via the API
payload <- list(
  'seriesid'  = c('LAUCN360610000000004', 'LAUCN360610000000006'),
  'startyear' = 2007,
  'endyear'   = 2009)
response <- blsAPI(payload, 2)
json     <- fromJSON(response)

## Process results
apiDF <- function(data) {
  df  <- data.frame(matrix(unlist(data), nrow = length(data), byrow = TRUE))
  colnames(df) <- c("year", "period", "periodName", "value")
  return(df)
}


unemployed.df  <- apiDF(json$Results$series[[1]]$data)
labor.force.df <- apiDF(json$Results$series[[2]]$data)

## Change value type from character to numeric
unemployed.df[,4]  <- as.numeric(unemployed.df[,4])
labor.force.df[,4] <- as.numeric(labor.force.df[,4])

## Rename value prior to merging
names(unemployed.df)[4]  <- 'unemployed'
names(labor.force.df)[4] <- 'labor.force'

## Merge data frames
df <- merge(unemployed.df, labor.force.df)

## Create date and unemployement rate
df$unemployment.rate <- df$unemployed / df$labor.force
df$date <- as.POSIXct(strptime(paste0('1',df$periodName,df$year), '%d%B%Y'))

## Beginning and end dates for the Great Recession (used in shaded area)
gr.start <- as.POSIXct(strptime('1December2007', '%d%B%Y'))
gr.end   <- as.POSIXct(strptime('1June2009', '%d%B%Y'))

## Plot the data
ggplot(df) + geom_rect(aes(xmin = gr.start, xmax = gr.end, ymin = -Inf, ymax = Inf), alpha = 0.4, fill="#DDDDDD") + geom_line(aes(date, unemployment.rate*100)) + ylab('Percent of labor force')  + xlab('Great Recession shaded in gray') + ggtitle('Unemployment Rate for Manhattan, NY (Jan 2007 to Dec 2010)') + theme_bw()

Quarterly Census of Employment and Wages (QCEW) Open Data

The BLS has made QCEW data available through an open data access option. This package can access this data.

## Request the first quarter of 2017 for the state of Michigan
MichiganData <- blsQCEW('Area', year='2017', quarter='1', area='26000')

Please see the help file for more options and example code.

Labor Area Unemployment Statistics Function

The laus_get_data() function is a wrapper of the blsAPI() function that makes it easier to get the labor area unemployment data without knowing the Series ID for the specific area and measure you want. A few examples of a measure would be the unemployment rate, or the labor force.

Example

This example pulls the unemployment rate for California, Florida, Texas, and Nevada from 2019 to 2021.

library(rjson)
library(blsAPI)
library(dplyr)

unemployment_rate <- laus_get_data(c("California", "Florida", "Texas", "Nevada"), "unemployment rate", 2019, 2021)

The resulting data frame will look like this for the first four rows

year	period	periodName	Unemployment_Rate	Location
2021	M07	July	2.2	California
2021	M06	June	2.0	California
2021	M05	May	1.8	California
2021	M04	April	2.0	California

For more examples of this function and to learn more about it type ?laus_get_data in your R console.

Learning More

With the basics described above you can get started with the BLS API right away. To learn more see:

• BLS API Home
• BLS API FAQ
• BLS Help & Tutorials: Series ID Formats
• Register for BLS API v 2.0