Retrieving Occupational Employment and Wage Data with blsAPI in R

Understanding the blsAPI Package in R

The Bureau of Labor Statistics API (blsAPI) provides access to various employment and wage statistics from the United States. In this article, we will explore how to use the blsAPI package in R to retrieve occupational employment and wage data for a specific occupation.

Installing the Required Packages

Before proceeding with the tutorial, ensure that you have installed the necessary packages:

# Install required libraries
library(blsAPI)
library(tidyverse)

Understanding the `OEWS_IDSeries` Function

The OEWS_IDSeries function is used to create a unique series ID for the Occupational Employment and Wage Statistics (OEWS) API. The function takes several arguments:

Prefix: The prefix for the OEWS series (default: “OE”).
SeasonalAdjust: The seasonal adjustment type (default: “U” for Unadjusted).
AreaType: The area type (default: “N” for National).
Area: The two-digit Area Code (default: “0000000” for the United States as a whole).
Industry: The three-digit Industry Code (default: “111000” for All Industries).
Occupation: The four-digit Occupation Code (default: “110000” for All Occupations).

The function returns a string in the format Prefix-Prefix-SeasontalAdjust-AreaType-Area-Industry-Occupation-Data Type.

Creating an ID Series

To create an ID series, you can use the following function:

# Create an ID series
OEWS_IDSeries <- function(Prefix = "OE", 
                           SeasonalAdjust = "U", 
                           AreaType = "N", 
                           Area = "0000000", 
                           Industry = "111000",
                           Occupation = "110000", 
                           DataType = "01"){
  paste(c(Prefix, SeasonalAdjust, AreaType, Area, Industry, Occupation, DataType), collapse = "") 
}

# Example usage:
test <- OEWS_IDSeries(Area = "0000000", #National
                     Occupation = "152041", #Statistics Occupation
                     Industry = "000000", #Cross-industry, Private, Federal, State, and Local Government
                     DataType = "01") #Employment

print(test)  # Output: OEUN000000000000015204101

Making a Request to the blsAPI

To make a request to the blsAPI, you can use the following function:

# Make an API request
blsAPI <- function(payload, return_data_frame = T, api_version = 1){
  # Function implementation goes here...
}

# Example usage:
payload <- list(
  seriesid = test,
  startyear = 2018,
  endyear = 2020
)

single <- blsAPI(payload, return_data_frame = T, api_version = 1)
print(head(single))

Understanding the API Response

The API response is a data frame that contains various columns related to the requested occupation. The columns include:

year: The year for which the data was retrieved.
period: The period for which the data was retrieved (e.g., “A01” for annual).
periodName: The name of the period (e.g., “Annual”).
value: The value of the requested occupation.

Retrieving Data for Previous Years

To retrieve data for previous years, you need to adjust the startyear and endyear values in the payload. For example, if you want to retrieve data from 2020 to 2016, you can update the payload as follows:

payload <- list(
  seriesid = test,
  startyear = 2016,
  endyear = 2020
)

single <- blsAPI(payload, return_data_frame = T, api_version = 1)
print(head(single))

This will retrieve data for the occupations specified in the seriesid column, but with a start year of 2016 and an end year of 2020.

Troubleshooting

If you encounter issues while making an API request or retrieving data from the blsAPI, ensure that:

The startyear and endyear values are within the valid range (i.e., between 1963 and the current year).
The seriesid value is correct and corresponds to the occupation you want to retrieve.
The API version used in the request matches the version required by the blsAPI package.

Conclusion

In this article, we explored how to use the blsAPI package in R to retrieve occupational employment and wage data for a specific occupation. We discussed the OEWS_IDSeries function, which creates an ID series that can be used with the blsAPI. Additionally, we walked through making an API request, understanding the response format, and troubleshooting common issues.

Advanced Topics

Using Multiple Series IDs

You can retrieve data for multiple occupations by passing a vector of seriesid values in the payload:

# Example usage:
occupations <- c("152041", "152043")  # Statistics Occupation
payload <- list(
  seriesids = occupations,
  startyear = 2016,
  endyear = 2020
)

single <- blsAPI(payload, return_data_frame = T, api_version = 1)
print(head(single))

This will retrieve data for the specified occupations using multiple seriesid values.

Handling Errors and Exceptions

You can handle errors and exceptions by checking the response code and message:

# Example usage:
response <- blsAPI(payload, return_data_frame = T, api_version = 1)
if (response$code != 200) {
  stop(paste("Error:", response$message))
}

This will check if the API request was successful (200 OK) and raise an error message if not.

Customizing the API Request

You can customize the API request by passing additional parameters in the payload:

# Example usage:
payload <- list(
  seriesid = test,
  startyear = 2016,
  endyear = 2020,
  data_type = "02"  # Additional parameter: Quarterly Data
)

single <- blsAPI(payload, return_data_frame = T, api_version = 1)
print(head(single))

This will retrieve quarterly data for the specified occupation.

Example Use Case

The following example demonstrates how to use the blsAPI package in R to retrieve occupational employment and wage data for statistics occupations:

# Load required libraries
library(blsAPI)
library(tidyverse)

# Define an ID series for statistics occupations
OEWS_IDSeries <- function(Prefix = "OE", 
                           SeasonalAdjust = "U", 
                           AreaType = "N", 
                           Area = "0000000", 
                           Industry = "111000",
                           Occupation = c("152041", "152043"),  # Statistics Occupations
                           DataType = "01"){
  paste(c(Prefix, SeasonalAdjust, AreaType, Area, Industry, Occupation, DataType), collapse = "") 
}

# Create an ID series for statistics occupations
occupations <- OEWS_IDSeries(Occupation = c("152041", "152043"))

# Define the payload with start year and end year
payload <- list(
  seriesids = occupations,
  startyear = 2016,
  endyear = 2020
)

# Make an API request to retrieve data
single <- blsAPI(payload, return_data_frame = T, api_version = 1)

# Print the response
print(head(single))

This example demonstrates how to create an ID series for statistics occupations using the OEWS_IDSeries function and make an API request to retrieve occupational employment and wage data for those occupations.

Last modified on 2024-04-25