Download a survey and import it into R

Download a Qualtrics survey you own via API and import the survey directly into R.

fetch_survey(
  surveyID,
  last_response = deprecated(),
  start_date = NULL,
  end_date = NULL,
  unanswer_recode = NULL,
  unanswer_recode_multi = unanswer_recode,
  include_display_order = TRUE,
  limit = NULL,
  include_questions = NULL,
  save_dir = NULL,
  force_request = FALSE,
  verbose = TRUE,
  label = TRUE,
  convert = TRUE,
  import_id = FALSE,
  time_zone = NULL,
  breakout_sets = TRUE,
  add_column_map = TRUE,
  add_var_labels = TRUE,
  col_types = NULL,
  ...
)

Arguments

surveyID	String. Unique ID for the survey you want to download. Returned as id by the all_surveys function.
last_response	Deprecated.
start_date	String. Filter to only exports responses recorded after the specified date. Accepts dates as character strings in format "YYYY-MM-DD". Defaults to NULL.
end_date	String. Filter to only exports responses recorded before the specified date. Accepts dates as character strings in format "YYYY-MM-DD". Defaults to NULL.
unanswer_recode	Integer. Recode seen but unanswered questions with an integer-like value, such as 999. Defaults to NULL.
unanswer_recode_multi	Integer. Recode seen but unanswered multi-select questions with an integer-like value, such as 999. Defaults to value for unaswer_recode.
include_display_order	Display order information (such as for surveys with randomization).
limit	Integer. Maximum number of responses exported. Defaults to NULL (all responses).
include_questions	Vector of strings (e.g. c('QID1', 'QID2', 'QID3'). Export only specified questions. Defaults to NULL.
save_dir	String. Directory where survey results will be stored. Defaults to a temporary directory which is cleaned when your R session is terminated. This argument is useful if you'd like to store survey results. The downloaded survey will be stored as an RDS file (see readRDS).
force_request	Logical. fetch_survey() saves each survey in a temporary directory so that it can quickly be retrieved later. If force_request is TRUE, fetch_survey() always downloads the survey from the API instead of loading it from the temporary directory. Defaults to FALSE.
verbose	Logical. If TRUE, verbose messages will be printed to the R console. Defaults to TRUE.
label	Logical. TRUE to export survey responses as Choice Text or FALSE to export survey responses as values.
convert	Logical. If TRUE, then the fetch_survey function will convert certain question types (e.g. multiple choice) to proper data type in R. Defaults to TRUE.
import_id	Logical. If TRUE, use Qualtrics import IDs instead of question IDs as column names. Will also alter names in the column map, if used. Defaults to FALSE.
time_zone	String. A local timezone to determine response date values. Defaults to NULL which corresponds to UTC time. See https://api-test.qualtrics.com/docs/publicapidocs/docs/Instructions/dates-and-times.md for more information on format.
breakout_sets	Logical. If TRUE, then the fetch_survey function will split multiple choice question answers into columns. If FALSE, each multiple choice question is one column. Defaults to TRUE.
add_column_map	Logical. If TRUE, then a column map data frame will be added as an attribute to the main response data frame. This column map captures Qualtrics-provided metadata associated with the response download, such as an item description and internal ID's. Defaults to TRUE.
add_var_labels	Logical. If TRUE, then the item description from each variable (equivalent to the one in the column map) will be added as a "label" attribute using set_label. Useful for reference as well as cross-compatibility with other stats packages (e.g., Stata, see documentation in sjlabelled). Defaults to TRUE.
col_types	Optional. This argument provides a way to manually overwrite column types that may be incorrectly guessed. Takes a cols specification. See example below and cols for formatting details. Defaults to NULL. Overwritten by convert = TRUE.
...	Optional arguments, such as a fileEncoding (see fileEncoding argument in read_survey) to import your survey using a specific encoding.

See also

See https://api.qualtrics.com/reference/ for documentation on the Qualtrics API.

Examples

if (FALSE) {
# Register your Qualtrics credentials if you haven't already
qualtrics_api_credentials(
  api_key = "<YOUR-API-KEY>",
  base_url = "<YOUR-BASE-URL>"
)

# Retrieve a list of surveys
surveys <- all_surveys()

# Retrieve a single survey
mysurvey <- fetch_survey(surveyID = surveys$id[6])

mysurvey <- fetch_survey(
  surveyID = surveys$id[6],
  save_dir = tempdir(),
  start_date = "2018-01-01",
  end_date = "2018-01-31",
  limit = 100,
  label = TRUE,
  unanswer_recode = 999,
  verbose = TRUE,
  # Manually override EndDate to be a character vector
  col_types = readr::cols(EndDate = readr::col_character())
)

}