** WARNING: THIS IS MY OWN BRANCH THAT CONTAINS A LOT!!! OF UNTESTED CODE. USE AT OWN RISK **
Qualtrics allows users to create and disseminate online surveys. It is used by researchers and other analysts to field responses for the purposes of (academic) research. While users can manually download survey responses from Qualtrics, importing this data into R is cumbersome. The R package qualtRics focuses on the retrieval of survey data using the Qualtrics API and aims to reduce the pre-processing steps needed to prepare this data for analysis. Currently, the package is the only package on CRAN that offers such functionality, and is included in the official Qualtrics API documentation.
Note that your institution must support API access and that it must be enabled for your account. Whoever manages your Qualtrics account can help you with this. Please refer to the Qualtrics documentation to find your API token.
I am not affiliated with Qualtrics and they do not offer support for this package.
If you want to contribute or have questions/comments, please sign up to the Slack channel
To install this package, execute the following in R:
Or, if you want to install the latest development version, run:
All dependencies will be installed when you install
Periodically check this repository for updates and execute
devtools::install_github("ropensci/qualtRics") to update.
Currently, the package contains three core functions:
- getSurveys() fetches a list of all surveys that you own or have access to from Qualtrics.
- getSurvey() downloads a survey from Qualtrics and loads it into R.
- readSurvey() allows you to read CSV files you download manually from Qualtrics.
It further contains four helper functions:
- registerOptions() stores your API key and base url in environment variables.
- getSurveyQuestions() retrieves a data frame containing questions and question IDs for a survey.
- qualtRicsConfigFile() prints information on how to make a .qualtRics.yml configuration file that stores your qualtRics API key, base url and other options in your working directory.
- metadata() retrieves metadata about your survey, such as questions, survey flow, number of responses etc.
Note that you can only export surveys that you own, or to which you have been given administration rights.
Registering your Qualtrics credentials
There are two important credentials you need to authenticate with the Qualtrics API. These are your API key and institution-specific base url. The base url you pass to the qualtRics package should either look like this:
or like this:
The Qualtrics API documentation explains how you can find your base url.
There are two ways to register your Qualtrics credentials and other options in R. As in earlier versions of the qualtRics package, you can register your credentials at the start of each R session:
You can set some global options via the
- verbose: Logical. If TRUE, verbose messages will be printed to the R console. Defaults to TRUE.
- useLabels: Logical. TRUE to export survey responses as Choice Text or FALSE to export survey responses as values.
- convertvariables: Logical. If TRUE, then the function will convert certain question types (e.g. multiple choice) to proper data type in R. Defaults to TRUE. (see below for more information)
- useLocalTime: Logical. Use local timezone to determine response date values? Defaults to FALSE.
- dateWarning: Logical. Once per session, qualtRics will emit a warning about date conversion for surveys. You can turn this warning off by changing the flag to FALSE. Defaults to TRUE.
You can change some of these options without having to pass the
base_url parameters every time as long as you have registered the api token and base url previously:
The second method involves placing a configuration file called
.qualtRics.yml in your working directory.
Using a configuration file
qualtRics supports the use of a configuration file to store your Qualtrics credentials. Executing
qualtRicsConfigFile() returns information that explains how you can do this:
Copy-paste the lines between the dashes into a new plain text file, replace the values for the api_token and base_url if they are not yet filled out. and save it in your working directory as '.qualtRics.yml'. Execute '?qualtRics::qualtRicsConfigFile' to view an explanation of the additional arguments. Visit https://github.com/ropensci/qualtRics/blob/master/README.md#using-a-configuration-file for more information. -------------- api_token: <YOUR-API-TOKEN-HERE> base_url: <YOUR-ROOT-URL-HERE> verbose: TRUE uselabels: TRUE convertvariables: TRUE uselocaltime: FALSE datewarning: TRUE --------------
You can also call this function while passing
base_url values to the function, in which case
<YOUR-ROOT-URL-HERE> will be replaced by your credentials. After saving the file, you can register your credentials by calling
registerOptions() without passing any parameters.
When you load the qualtRics package, it will automatically look for a
.qualtRics.yml file in the working directory, in which case you don't need to call the
registerOptions() function to register your qualtRics credentials at the beginning of your session.
You can override your configuration file settings by calling
registerOptions() with the changes you want to make:
registerOptions(verbose=FALSE, useLabels=FALSE, base_url="myinstitution.qualtrics.com")
Setting up a config file
- Open an existing R project or start a new one. Then, open up an empty text file:
qualtRicsConfigFile(api_token="<YOUR-API-TOKEN-HERE>", base_url="<YOUR-ROOT-URL-HERE>")and copy-paste the text between the dashes to the empty text file:
- Save the file as
registerOptions()or restart your R session and execute
library(qualtRics)to load the configuration file.
You can edit your configuration file by executing
file.edit(".qualtRics.yml") in the R console.
Automatic conversion of variables
From version 2.5, qualtRics supports the automatic conversion of specific variable types (see table below) since users already specify most information needed for such a conversion when they design their survey.
For example, using the
metadata() function, you can pull in metadata about your survey questions:
# Get metadata for a survey md <- metadata(id) # Filter for questions md.f <- md$questions # Pick specific question QOI <- md.f$QID172807686 # View question type QOI$questionType
$type  "MC" $selector  "SAVR" $subSelector  "TX"
We see that this is a multiple choice question ("MC") with a single answer ("SAVR"). The data supplied also includes the different answers a user can give:
# Return question description lapply(QOI$choices, function(x) x$description)
$`1`  "Extremely useful" $`2`  "Very useful" $`3`  "Moderately useful" $`4`  "Slightly useful" $`5`  "Not useful at all"
This data can be used to turn the variable into a factor automatically.
Currently, the following data types are supported for automatic conversion:
|Multiple choice||Single answer||"MC", "SAVR"||2.5|
Load the package:
Register your Qualtrics credentials if required:
Get a data frame of surveys:
surveys <- getSurveys()
Export a survey and load it into R:
mysurvey <- getSurvey(surveyID = surveys$id, verbose = TRUE) # You can set this option globally # or pass it to the function.
You can add a from/to date to only retrieve responses between those dates:
surv <- getSurvey(surveys$id, startDate = "2016-09-18", endDate = "2016-10-01", useLabels = FALSE) # You can set this option # globally or pass it to this # function.
Note that your date and time settings may not correspond to your own timezone. You can find out how to do this here. See this page for more information about how Qualtrics handles dates and times. Keep in mind that this is important if you plan on using times / dates as cut-off points to filter data.
You may also reference a response ID.
getSurvey will then download all responses that were submitted after that response:
surv <- getSurvey(surveys$id, lastResponseId = "R_3mmovCIeMllvsER", useLabels = FALSE, verbose = TRUE)
You can filter a survey for specific questions:
# Retrieve questions for a survey questions <- getSurveyQuestions(surveyID = surveys$id) # Retrieve a single survey, filtering for questions I want. mysurvey <- getSurvey(surveyID = surveys$id, save_dir = tempdir(), includedQuestionIds = c("QID1", "QID2", "QID3"), verbose=TRUE)
Note that dates are converted without a specific timezone in mind. You can specify your own timezone using these instructions.
You can store the results in a specific location if you like:
mysurvey <- getSurvey(surveyID = surveys$id, save_dir = "/users/jasper/desktop/", verbose = TRUE)
Note that surveys that are stored in this way will be saved as an RDS file rather than e.g. a CSV. Reading an RDS file is as straightforward as this:
mysurvey <- readRDS(file = "/users/jasper/desktop/mysurvey.rds")
You can read a survey that you downloaded manually using
mysurvey <- readSurvey("/users/jasper/desktop/mysurvey.csv")
To avoid special characters (mainly periods) in header names,
readSurvey uses question labels as the header names. The question belonging to that label is then added using the sjlabelled package. Qualtrics gives names to these labels automatically, but you can easily change them.
In order to avoid problems when importing the data, do not use newlines in question labels and descriptions.
For specific information about the Qualtrics API, you can refer to the official documentation.
Should you encounter any bugs or issues, please report them here
If you have a request (like adding a new argument), please leave it as an issue here
Contributions are welcome from anyone subject to the following rules:
- Abide by the code of conduct.
- Follow the style guide from Hadley Wickham's R Packages
- All contributions must be consistent with the package license (GPL-3)
- Submit contributions as a pull request. Clearly state what the changes are and try to keep the number of changes per pull request as low as possible.
- If you make big changes, add your name to the 'Author' field.
- Jason Bryer wrote an R package to work with the previous version of the Qualtrics API
- QualtricsTools creates automatic reports in shiny.
- qsurvey by James Dunham focuses on testing and review of surveys before fielding, and analysis of responses afterward.
News and changes
View news about qualtRics here
Thanks to everyone who lets me know about issues, bugs etc. I appreciate your help a lot. Special thanks to those who add code! h/t @phoebewong, @samuelkaminsky, @eknud, @strengejacke, Adrian Brugger and Stefan Borer.