Download a survey and import it into R

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

Usage

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

Arguments

surveyID: String. Unique ID for the survey you want to download. Returned as id by the all_surveys function.
limit: Integer. Maximum number of responses exported. Defaults to NULL (all responses).
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.
time_zone: String. A local timezone to determine response date values. Defaults to NULL, which corresponds to system local time. See "Dates and Times" from Qualtrics for more information on format.
include_display_order: Display order information (such as for surveys with randomization).
include_metadata, include_questions, include_embedded: Character vector. Specify variables to include in download. Defaults to NULL (keep all). NA or character() excludes all variables for that category. See Details for unique requirements for each inclusion argument.
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.
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.
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.
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.
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.
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.
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()).
last_response: Deprecated.

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.

The three include_* arguments each have different requirements to properly specify what to the Qualtrics API.

include_metadata:

Elements must be one of the 17 Qualtrics metadata variables, listed here in their default order: StartDate (startDate), EndDate (endDate), Status (status), IPAddress (ipAddress), Progress (progress), Duration (in seconds) (duration), Finished (finished), RecordedDate (recordedDate), ResponseId (_recordId), RecipientLastName (recipientLastName), RecipientFirstName (recipientFirstName), RecipientEmail (recipientEmail), ExternalReference (externalDataReference), LocationLatitude (locationLatitude), LocationLongitude (locationLongitude), DistributionChannel (distributionChannel), UserLanguage (userLanguage). Names in parentheses represent those returned when argument import_id is set to TRUE. However, the function can always generate a suitable request from either format, and names are not case-sensitive. Duplicate names will be silently dropped, and data frame will contain variables in the order specified after de-duplication.

include_questions:

Desired variables must be specified using Qualtrics's own unique internal ID's, rather than any user-specified names. All such ID's start with "QID" followed by a number. If needed, a column map linking user-specified ID's to QID's can be quickly obtained by calling:

Note that while QID's are unique for each "question" in the Qualtrics sense, there may not be a 1:1 relationship between QID's and columns in the response data frame. If, for example, the question with ID QID5 is a multiple choice item with a text box added to the third choice, the downloaded response data frame may include two associated variables: "QID5" (the multiple choice selection) and "QID5_3_TEXT" (the text box). Both variables will be returned by include_questions = "QID5". Additionally, if randomization is used any associated display ordering variables will also be present (assuming include_display_order = TRUE). Currently, separating these via the API does not appear possible (e.g., include_questions = "QID5_3_TEXT" will produce an API error).

include_embedded:

This argument accepts the user-specified names of any embedded data variables in the survey being accessed.

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())
)

}

Usage

Arguments

Details

See also

Examples

About

Community

Resources