Qualtrics API
You have to authenticate every call you make to the Qualtrics API. Qualtrics offers two ways to authenticate: OAuth and API key. These steps are for key-based authentication, which works with the qualtRics R package. If you will not be using qualtRics and want the additional security OAuth offers, see the API Quick Start. Reach out via the #qualtrics or #r-users-group Slack channels with any questions!
Get Your API Key
Log in to Qualtrics (see Accessing Qualtrics), then click the round My Account icon in the upper right (1) and select Account Settings from the drop-down menu that appears (2):
When you click Account Settings, Qualtrics will route you to the User Settings tab. From there, click into the Qualtrics IDs tab:
Once you are in the Qualtrics IDs tab, find the box labeled API. You only need to generate a Qualtrics API token (also called a key) once. If you previously generated your token, it will display in the box. If no token displays under API, click generate token:
Get Your Base URL
Find the box labeled User in your Qualtrics ID tab. It contains your datacenter ID:
Your base URL is your datacenter ID followed by qualtrics.com. For example, if your datacenter ID is abc123, your base URL is abc123.qualtrics.com.
Configure RStudio
Open RStudio and use the standard syntax to install and load qualtRics:
install.packages("qualtRics")
library(qualtRics)Store your Qualtrics API key and base URL (from above) for use across R sessions by calling the qualtRics function qualtrics_api_credentials():
qualtrics_api_credentials(api_key = "<YOUR_API_KEY>",
base_url = "<YOUR_API_TOKEN>",
install = TRUE)
Tip
Throughout this website, <> indicate blanks you need to fill in before you run the code provided.
Use the standard syntax to install and load usethis:
install.packages("usethis")
library(usethis)Run this line of code in your console to open your .Renviron file:
usethis::edit_r_environ()If you see these lines in your .Renviron file, you have successfully stored your Qualtrics credentials for use across R sessions:
QUALTRICS_API_KEY = "<YOUR_API_KEY>"
QUALTRICS_BASE_URL = "<YOUR_BASE_URL>"Get Your Data
Now that you have a Qualtrics API key and RStudio setup for key-based authentication, you can use the qualtRics package with the Qualtrics API to import your data straight from Qualtrics into R.
Get Your Survey ID
Your survey’s ID lives in its Qualtrics URL. The easiest place to find it is in your survey’s Distributions tab. Login to Qualtrics, go into your survey, and click Distributions. Your survey ID is the alphanumeric string after ContextSurveyID= in the URL:
Alternatively, run qualtRics::all_surveys() in your RStudio console to retrieve a list of all the Qualtrics surveys you own or have access to. But, if you have access to more than a few surveys, getting the ID from the survey URL will likely be faster than searching through all your surveys in the console for it.
Once you get your survey ID, you can store it in a variable:
id <- "<SURVEY_ID>" # optional but helpful
Tip
Throughout this website, <> indicate blanks you need to fill in before you run the code provided.
Meet the Functions
See this vignette for a full introduction to the functions in the qualtRics package. Briefly:
qualtrics_api_credentials() stores your API key and base URL for use across R sessions.
all_surveys() fetches a list of all the Qualtrics surveys you own or have access to.
fetch_survey() downloads a survey from Qualtrics and loads it into R.
read_survey() reads a file you download manually from Qualtrics into R.
survey_questions() retrieves a data frame with the ID and text (which Qualtrics calls a “label”) of each question in a survey.
extract_colmap() returns a column map with information about each column in a data frame of downloaded response data.
metadata() retrieves metadata about your survey, such as response counts and details about survey flow.
Make Your API Call
Copy and paste the starter code below into your project file and tailor it to meet your needs by adjusting the arguments in fetch_survey(). Reference the inline comments and the function documentation, which you can access by running ?fetch_survey() in your console, for help understanding each argument. You can delete any arguments you leave set to the defaults. Many of the defaults will serve you well, but note that the tech team recommends alternatives to the defaults for label, convert, and force_request.
library(qualtRics)
survey <- fetch_survey("<SURVEY_ID>",
# max number of responses to export
# defaults to NULL (export all responses)
limit = NULL,
# start and/or end dates if exporting
# a time bound subset of responses
# both default to NULL (export all responses)
start_date = NULL,
end_date = NULL,
# time zone for date/time metadata variables
# defaults to NULL (use current system time zone)
time_zone = NULL,
# for surveys with display randomization,
# download additional variables indicating
# the randomization pattern for each case
# defaults to TRUE
include_display_order = TRUE,
# specify metadata fields to download
# defaults to NULL (download all fields)
include_metadata = NULL,
# specify questions to download
# defaults to null (include all questions)
include_questions = NULL,
# specify embedded data variables to download
# defaults to NULL (download all embedded variables)
include_embedded = NULL,
# specify value for seen-but-unanswered questions
# defaults to NA when unanswer_recode = NULL
unanswer_recode = NULL,
# specify values for seen-but-not-selected answer choices
# for multi-select multiple-choice questions
# (i.e., "check all that apply" questions)
# defaults to unanswer_recode value
# (NA unless otherwise specified, see above)
unanswer_recode_multi = NULL,
# return multi-value fields (i.e., answer choices
# for multi-select multiple choice questions)
# in different columns
# defaults to TRUE
breakout_sets = TRUE,
# use Qualtrics import IDs (e.g. "QID123")
# instead of user-modifiable names (e.g., default names
# like "Q3" or custom names)
# defaults to FALSE
import_id = FALSE,
# return answer choice text instead of recoded numeric values
# defaults to TRUE, but the tech team recommends FALSE because
# numbers work better for data visualization and analysis
label = FALSE,
# automatically convert certain questions
# to the proper data type in R
# defaults to TRUE but must be FALSE
# if label = FALSE (see above)
convert = FALSE,
# add extractable metadata to the response data frame
# (see ?extract_colmap)
# defaults to TRUE
add_column_map = TRUE,
# add the item description for each variable
# as a label attribute (useful for reference and
# cross-compatibility with other stats packages like Stata)
# defaults to TRUE
add_var_labels = TRUE,
# manually overwrite column types that make be
# guessed incorrectly
# defaults to NULL
# overwritten by convert = TRUE (see above)
col_types = NULL,
# Redownload responses from Qualtrics every time
# defaults to FALSE, but the tech team recommends TRUE
# to be sure your data is always up to date
force_request = TRUE,
# print verbose messages in the R console
# defaults to TRUE
verbose = TRUE,
# specify directory for storing survey results
# defaults to a temporary directory that clears
# when your R session terminates
save_dir = NULL)