qualtRics R Package

The qualtRics R package provides a bridge between the Qualtrics user interface and R by automating the retrieval of survey data via the Qualtrics API. It aims to reduce pre-processing steps by handling the requesting, downloading, unpacking, and importing of survey data directly into R.

Key features include:

• Automatic conversion of single-choice multiple-choice questions.
• Automatic conversion of ordinal data to ordered factors using Qualtrics metadata.
• Support for both current and legacy data formats via readSurvey().
• Secure credential management by allowing users to store API credentials in a file within the R project root directory, which loads automatically.

To authenticate with the Qualtrics API, you need your API key and your datacenter-specific base URL. The base URL should be in the format yourdatacenterid.qualtrics.com (do not include https://).

Use qualtrics_api_credentials() to store these as environment variables (QUALTRICS_API_KEY and QUALTRICS_BASE_URL) in your .Renviron file. Setting install = TRUE writes them to the file for persistent use across R sessions.

library(qualtRics)

qualtrics_api_credentials(api_key = "<YOUR-QUALTRICS_API_KEY>", 
                          base_url = "<YOUR-QUALTRICS_BASE_URL>",
                          install = TRUE)

# Reload environment to use credentials without restarting R
readRenviron("~/.Renviron")

Once credentials are configured, the standard workflow involves listing available surveys and then fetching the data for a specific survey ID.

1. List all surveys: surveys <- all_surveys()
2. Fetch a specific survey: mysurvey <- fetch_survey(surveyID = surveys$id[index], verbose = TRUE)

# 1. See what surveys are available
surveys <- all_surveys() 

# 2. Download data from a specific survey (e.g., the sixth one) directly into R
mysurvey <- fetch_survey(surveyID = surveys$id[6], 
                         verbose = TRUE)

You can install the stable version of qualtRics from CRAN, or install the development version directly from GitHub using the remotes or devtools package.

# Install from CRAN
install.packages("qualtRics")

# Install development version from GitHub
install.packages("remotes")
remotes::install_github("ropensci/qualtRics")

The package provides core functions to interact with the Qualtrics API and manage survey data:

• all_surveys(): Fetches a list of all surveys you own or have access to.
• fetch_survey(surveyID, ...): Downloads a specific survey from Qualtrics and loads it into R.
• read_survey(): Reads CSV files that were downloaded manually from the Qualtrics browser interface.

Helper functions:

• survey_questions(): Retrieves a data frame of questions and question IDs.
• extract_colmap(): Retrieves a detailed mapping from columns to labels.
• metadata(): Retrieves survey metadata (questions, survey flow, response counts, etc.).

The package provides three core functions for the survey data workflow:

1. getSurveys(): Retrieves a data frame containing an overview of all surveys accessible to the user.
2. getSurvey(): Downloads and unpacks survey data for a specific survey using its unique survey ID.
3. readSurvey(): Imports data into R. This function can be used to import data retrieved via getSurvey() or to import manual data exports. It supports both current and legacy Qualtrics data formats.

Beyond data retrieval, qualtRics provides several helper functions to understand survey structure:

• survey_questions(): Retrieves a data frame containing questions and question IDs.
• extract_colmap(): Retrieves a data frame with detailed mapping from columns to labels.
• metadata(): Retrieves metadata about a survey, including questions, survey flow, and response counts.