Package 'qualtRics'

Description

Retrieve a data frame of all mailing lists from Qualtrics

Usage

all_mailinglists()

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.

Examples

## Not run: 
# 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 all mailing lists
mailinglists <- all_mailinglists()

## End(Not run)

Description

Retrieve a data frame of all active surveys on Qualtrics

Usage

all_surveys()

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

## Not run: 
# 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 all 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 = "UNANS",
  verbose = TRUE
)

## End(Not run)

Description

Retrieve a data frame containing survey column mapping

Usage

column_map(surveyID)

Arguments

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

## Not run: 
# 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 column mapping for a survey
mapping <- column_map(surveyID = surveys$id[6])

# Retrieve a single survey, filtering for specific questions
mysurvey <- fetch_survey(
  surveyID = surveys$id[6],
  save_dir = tempdir(),
  include_questions = c("QID1", "QID2", "QID3"),
  verbose = TRUE
)

## End(Not run)

Description

Helper function to extract the column map attached to a response data download obtained from fetch_survey() (using the default add_column_map = TRUE)

Usage

extract_colmap(respdata)

Arguments

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.

Examples

## Not run: 
# Retrieve a list of surveys
surveys <- all_surveys()

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

# Extract column mapping for survey
extract_colmap(mysurvey)

## End(Not run)

Description

Download complete survey description using the Qualtrics v3 "Get Survey" API endpoint.

Usage

fetch_description(surveyID, elements = NULL, legacy = FALSE, ...)

Arguments

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.

Value

A list containing survey description metadata. The contents of the returned list depend on elements.

Examples

## Not run: 
# 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()

# Get description for a survey
descrip <- fetch_description(surveyID = surveys$id[6])

# Get metadata with specific elements
descrip_specific <- fetch_description(
  surveyID = id,
  elements = c("questions", "flow")
)


## End(Not run)

Description

Download distribution history data for a distribution from Qualtrics

Usage

fetch_distribution_history(distributionID)

Arguments

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.

Examples

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

surveys <- all_surveys()
distributions <- fetch_distributions(surveys$id[1])
distribution_history <- fetch_distribution_history(distributions$id[1])

## End(Not run)

Description

Download distribution data for a survey from Qualtrics

Usage

fetch_distributions(surveyID)

Arguments

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.

Examples

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

surveys <- all_surveys()
distributions <- fetch_distributions(surveys$id[1])

## End(Not run)

Description

Fetch a unique Qualtrics survey ID based on survey name in the Qualtrics UI

Usage

fetch_id(.data, survey_name, partial_match = FALSE)

Arguments

Details

Survey names in the Qualtrics platform are not required to be unique, but the survey_name argument for this function must be unique. If input results in multiple surveys being matched, will error with a list of up to 5 matches & their IDs

Examples

## Not run: 
# 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 surveyID for a unique survey
my_id <- fetch_id(surveys, "Unique Survey Name")


## End(Not run)

Description

Download a mailing list from Qualtrics

Usage

fetch_mailinglist(mailinglistID)

Arguments

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.

Examples

## Not run: 
# 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 all mailing lists
mailinglists <- all_mailinglists()

# Retrieve a single mailing list
mailinglist <- fetch_mailinglist(mailinglists$id[1])

## End(Not run)

Description

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,
  strip_html = TRUE,
  col_types = NULL,
  verbose = TRUE,
  tmp_dir = tempdir(),
  last_response = deprecated(),
  force_request = deprecated(),
  save_dir = deprecated()
)

Arguments

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.

start_date & end_date arguments

The Qualtrics API endpoint for this function treats start_date and end_date slightly differently; end_date is exclusive, meaning only responses recorded up to the moment before the specified end_date will be returned. This permits easier automation; a previously-used end_date can become the start_date of a subsequent request without downloading duplicate records.

As a convenience for users working interactively, the qualtRics package also accepts Date(-like) input to each argument, which when used implies a time of 00:00:00 on the given date (and time zone). When a Date(-like) is passed to end_date, however, the date will be incremented by one before making the API request. This adjustment is intended to provide interactive users with more intuitive results; for example, specifying "2022/06/02" for both start_date and end_date will return all responses for that day, (instead of the zero responses that would return if end_date was not adjusted).

Inclusion/exclusion arguments

The three ⁠include_*⁠ arguments each have different requirements:

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 are those returned by the API endpoint when import_id is set to TRUE. The argument include_metadata can accept either format regardless of import_id setting, and names are not case-sensitive. Duplicate elements passed to include_metadata will be silently dropped, with the de-duplicated variable located in the first position.

include_questions

Qualtrics uniquely identifies each question with an internal ID that takes the form "QID" followed by a number, e.g. QID5. When using include_questions, these internal IDs must be used rather than user-customizable variable names (which need not be unique in Qualtrics). If needed, a column map linking customizable names to QID's can be quickly obtained by calling:

my_survey <- fetch_survey(
    surveyID = {survey ID},
    limit = 1,
    add_column_map = TRUE
)
extract_colmap(my_survey)

Note that while there is one QID for each "question" in the Qualtrics sense, each QID may still map to multiple columns in the returned data frame. If, for example, a "question" with ID QID5 is a multiple-choice item with a text box added to the third choice, the returned data frame may have two related columns: "QID5" for the multiple choice selection, and "QID5_3_TEXT" for the text box (or, more typically, their custom names). Setting include_questions = "QID5" will always return both columns. Similarly, "matrix" style multiple-choice questions will have a column for each separate row of the matrix. Also, when include_display_order = TRUE, display ordering variables for any randomization will be included. Currently, separating these sub-questions via the API does not appear possible (e.g., include_questions = "QID5_3_TEXT" will result in an API error).

include_embedded

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

See Also

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

Examples

## Not run: 
# 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
my_survey <- fetch_survey(surveyID = surveys$id[6])

my_survey <- fetch_survey(
  surveyID = surveys$id[6],
  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())
)


## End(Not run)

Description

Download distribution links for a distribution from Qualtrics

Usage

list_distribution_links(distributionID, surveyID)

Arguments

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.

Examples

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

surveys <- all_surveys()
distributions <- fetch_distributions(surveys$id[1])
distribution_links <- list_distribution_links(distributions$id[1], surveyID = surveys$id[1])

## End(Not run)

Description

Using this function, you can retrieve metadata about your survey. This information includes question metadata (type, options, choices, etc), number of responses, general metadata, survey flow, etc.

Usage

metadata(surveyID, get = NULL, questions = NULL)

Arguments

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.

Examples

## Not run: 
# 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()

# Get metadata for a survey
md <- metadata(surveyID = surveys$id[6])

# Get metadata with specific elements
md_specific <- metadata(
  surveyID = id,
  get = c("flow")
)

# Get specific question metadata
question_specific <- metadata(
  surveyID = id,
  get = c("questions"),
  questions = c("Q1", "Q2")
)

# Example of a metadata file
file <- system.file("extdata", "metadata.rds", package = "qualtRics")

# Load
metadata_ex <- readRDS(file = file)

## End(Not run)

Description

This function adds your Qualtrics API key and base URL to your .Renviron file so it can be called securely without being stored in your code. After you have installed these two credentials, they can be called any time with Sys.getenv("QUALTRICS_API_KEY") or Sys.getenv("QUALTRICS_BASE_URL"). If you do not have an .Renviron file, the function will create one for you. If you already have an .Renviron file, the function will append the key to your existing file, while making a backup of your original file for disaster recovery purposes.

Usage

qualtrics_api_credentials(
  api_key,
  base_url,
  overwrite = FALSE,
  install = FALSE,
  report = FALSE
)

Arguments

Examples

## Not run: 
qualtrics_api_credentials(
  api_key = "<YOUR-QUALTRICS_API_KEY>",
  base_url = "<YOUR-QUALTRICS_BASE_URL>",
  install = TRUE
)
# Reload your environment so you can use the credentials without restarting R
readRenviron("~/.Renviron")
# You can check it with:
Sys.getenv("QUALTRICS_API_KEY")

# If you need to overwrite existing credentials:
qualtrics_api_credentials(
  api_key = "<YOUR-QUALTRICS_API_KEY>",
  base_url = "<YOUR-QUALTRICS_BASE_URL>",
  overwrite = TRUE,
  install = TRUE
)
# Reload your environment to use the credentials

## End(Not run)

Description

Reads comma separated CSV files generated by Qualtrics software. The second line containing the variable labels is imported. Repetitive introductions to matrix questions are automatically removed. Variable labels are stored as attributes.

Usage

read_survey(
  file_name,
  strip_html = TRUE,
  import_id = FALSE,
  time_zone = NULL,
  legacy = FALSE,
  add_column_map = TRUE,
  add_var_labels = TRUE,
  col_types = NULL
)

Arguments

Value

A data frame. Variable labels are stored as attributes. They are not printed on the console but are visibile in the RStudio viewer.

Examples

## Not run: 
# Generic use of read_survey()
df <- read_survey("<YOUR-PATH-TO-CSV-FILE>")

## End(Not run)
# Example using current data format
file <- system.file("extdata", "sample.csv", package = "qualtRics")
df <- read_survey(file)

# Example using legacy data format
file <- system.file("extdata", "sample_legacy.csv", package = "qualtRics")
df <- read_survey(file, legacy = TRUE)

# Example changing column type
file <- system.file("extdata", "sample.csv", package = "qualtRics")
# Force EndDate to be a string
df <- read_survey(file, col_types = readr::cols(EndDate = readr::col_character()))

Description

Retrieve a data frame containing question IDs and labels

Usage

survey_questions(surveyID)

Arguments

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

## Not run: 
# 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 questions for a survey
questions <- survey_questions(surveyID = surveys$id[6])

# Retrieve a single survey, filtering for specific questions
mysurvey <- fetch_survey(
  surveyID = surveys$id[6],
  save_dir = tempdir(),
  include_questions = c("QID1", "QID2", "QID3"),
  verbose = TRUE
)

## End(Not run)