Download a survey and import it into R

Source: R/fetch_survey.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,
  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. 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.qualtrics.com/instructions/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.
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())
)
}