Skip to content

Latest commit

 

History

History
168 lines (123 loc) · 7.02 KB

README.md

File metadata and controls

168 lines (123 loc) · 7.02 KB
Raw

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: