knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
This project contains an R package to download surveys from Qualtrics using the API.
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.
Currently, the package contains three core functions:
It further contains four helper functions:
Note that you can only export surveys that you own, or to which you have been given administration rights.
There are two ways to register your Qualtrics credentials (your API key and institution-specific root url) 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:
registerOptions(api_token="<YOUR-API-TOKEN>", root_url="<YOUR-ROOT-URL>")
You can set some global options via the registerOptions()
function:
You can change some of these options without having to pass the api_token
or root_url
parameters every time as long as you have registered the api token and root url previously:
registerOptions(verbose=FALSE, useLocalTime=TRUE)
The second method involves placing a configuration file called .qualtRics.yml
in your working directory.
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 root_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> root_url: <YOUR-ROOT-URL-HERE> verbose: TRUE uselabels: TRUE convertvariables: TRUE uselocaltime: FALSE datewarning: TRUE --------------
You can also call this function while passing api_token
and root_url
values to the function, in which case <YOUR-API-TOKEN-HERE>
and <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, root_url="myinstitution.qualtrics.com")
Open an existing R project or start a new one. Then, open up an empty text file:
knitr::include_graphics("https://raw.githubusercontent.com/ropensci/qualtRics/master/img/config_step1.png")
Execute qualtRicsConfigFile(api_token="<YOUR-API-TOKEN-HERE>", root_url="<YOUR-ROOT-URL-HERE>")
and copy-paste the text between the dashes to the empty text file:
knitr::include_graphics("https://raw.githubusercontent.com/ropensci/qualtRics/master/img/config_step2.png")
Save the file as .qualtRics.yml
and execute registerOptions()
or restart your R session and execute library(qualtRics)
to load the configuration file.
Load the package:
library(qualtRics)
Register your Qualtrics credentials if required:
registerOptions(api_token="<YOUR-API-TOKEN>", root_url="<YOUR-ROOT-URL>")
Get a data frame of surveys:
surveys <- getSurveys()
Export a survey and load it into R:
mysurvey <- getSurvey(surveyID = surveys$id[6], 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(survs$id[4], 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(survs$id[4], 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[6]) # Retrieve a single survey, filtering for questions I want. mysurvey <- getSurvey(surveyID = surveys$id[6], 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[6], 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 readSurvey
:
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.
knitr::include_graphics("https://raw.githubusercontent.com/ropensci/qualtRics/master/img/qualtricsdf.png")
You can edit your configuration file by executing file.edit(".qualtRics.yml")
in the R console.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.