qualtRics (version 3.1.6)

fetch_survey: Download a survey and import it into R

Description

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

Usage

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 base::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 "Dates and Times" from Qualtrics 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 sjlabelled::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 readr::cols() specification. See example below and readr::cols() for formatting details. Defaults to NULL. Overwritten by convert = TRUE.

Details

If the request to the Qualtrics API made by this function fails, the request will be retried. If you see these failures on a 500 error (such as a 504 error) be patient while the request is retried; it will typically succeed on retrying. If you see other types of errors, retrying is unlikely to help.

See Also

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

Examples

if (FALSE) {
# Register your Qualtrics credentials if you haven't already
qualtrics_api_credentials(
  api_key = "",
  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())
)

}