| Type: | Package |
| Title: | Download 'Qualtrics' Survey Data |
| Version: | 3.2.1 |
| Description: | Provides functions to access survey results directly into R using the 'Qualtrics' API. 'Qualtrics' https://www.qualtrics.com/about/ is an online survey and data collection software platform. See https://api.qualtrics.com/ for more information about the 'Qualtrics' API. This package is community-maintained and is not officially supported by 'Qualtrics'. |
| License: | MIT + file LICENSE |
| URL: | https://docs.ropensci.org/qualtRics/, https://github.com/ropensci/qualtRics |
| BugReports: | https://github.com/ropensci/qualtRics/issues |
| Imports: | archive, cli, dplyr (≥ 1.0), fs, glue, httr, jsonlite, lifecycle, lubridate, purrr, readr, rlang, sjlabelled, stringr, tibble, tidyr, withr |
| Suggests: | covr, knitr, rmarkdown, testthat (≥ 3.0.0), vcr (≥ 1.2.0), webmockr |
| VignetteBuilder: | knitr |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2024-08-16 15:52:29 UTC; juliasilge |
| Author: | Jasper Ginn [aut],
Jackson Curtis [ctb],
Shaun Jackson [ctb],
Samuel Kaminsky [ctb],
Eric Knudsen [ctb],
Joseph O'Brien [aut],
Daniel Seneca [ctb],
Julia Silge  [aut,
cre],
Phoebe Wong [ctb] |
| Maintainer: | Julia Silge <julia.silge@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2024-08-16 16:20:02 UTC |
Retrieve a data frame of all mailing lists from 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)
Retrieve a data frame of all active surveys on Qualtrics
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)
General check that credentials are present
Description
General check that credentials are present
Usage
check_credentials()
Check if downloaded file already exists
Description
Check if downloaded file already exists
Usage
check_existing_download(file_location, surveyID, verbose = TRUE)
Arguments
file_location |
(potential) path to previous download |
surveyID |
Qualtrics survey ID |
verbose |
whether to report if match is found |
Check if httr GET result contains a warning
Description
Check if httr GET result contains a warning
Usage
check_for_warnings(resp)
Arguments
resp |
object returned by |
Checking and re-formatting base_url:
Description
Checking and re-formatting base_url:
Usage
checkarg_base_url(base_url)
col_types must be a col_spec object from readr
Description
col_types must be a col_spec object from readr
Usage
checkarg_col_types(col_types)
Check conditions around combinations of convert, label, and breakout_sets
Description
Check conditions around combinations of convert, label, and breakout_sets
Usage
checkarg_convert_label_breakouts(convert, label, breakout_sets)
Title Check date-time-like inputs and convert them to ISO8601 (with time zone)
Description
Title Check date-time-like inputs and convert them to ISO8601 (with time zone)
Usage
checkarg_datetime(date_arg, time_zone = NULL, endofday = FALSE)
Arguments
date_arg |
Date, POSIX(c/l)t date/time, or parseable string in YYYY(/-)MM(/-)DD format, optionally with a space and HH:MM:SS in 24 hour time. Intended to be converted to ISO8601 string for use in Qualtrics API call |
time_zone |
Optional arg for time zone specification, defaults to system local timezone. |
endofday |
Boolean. If TRUE, if the entry has no time information (only date), then result will have 23:59:59 (end of day) versus the implicit 00:00:00 (start). Intended for, e.g., 'end_date' argument in fetch_survey(). This allows the intuitive expectation where entering end_date = 2022/05/05 includes rather than excludes cases on 05/05 itself. |
Value
single string date/time formatted in ISO8601
Check if elements given in fetch_description are properly specified
Description
Check if elements given in fetch_description are properly specified
Usage
checkarg_elements(elements)
Check if data for fetch_id() is correct
Description
Check if data for fetch_id() is correct
Usage
checkarg_fetch_id_data(.data)
Check if survey file specified in file_name exists
Description
Check if survey file specified in file_name exists
Usage
checkarg_file_name(file_name)
Check if elements given in metadata's 'get' are properly specified
Description
Check if elements given in metadata's 'get' are properly specified
Usage
checkarg_get(get)
Check include_embedded and format for API call:
Description
Check include_embedded and format for API call:
Usage
checkarg_include_embedded(include_embedded)
Check that include_metadata has the right elements & format for API call
Description
Check that include_metadata has the right elements & format for API call
Usage
checkarg_include_metadata(include_metadata)
Check that include_questions uses the QID format, and format for API call:
Description
Check that include_questions uses the QID format, and format for API call:
Usage
checkarg_include_questions(include_questions)
Is boolean (length-1 logical)
Description
Is boolean (length-1 logical)
Usage
checkarg_isboolean(arg)
Is character vector with no missing values:
Description
Is character vector with no missing values:
Usage
checkarg_ischaracter(arg, null_okay = TRUE)
Is integerish (length-1 numeric w/o any fractional component)
Description
Is integerish (length-1 numeric w/o any fractional component)
Usage
checkarg_isintegerish(arg, null_okay = TRUE)
Is string (length-1 character)
Description
Is string (length-1 character)
Usage
checkarg_isstring(arg, null_okay = TRUE)
Check limit for being integer >= 1:
Description
Check limit for being integer >= 1:
Usage
checkarg_limit(limit)
Check if the temporary directory exists:
Description
Check if the temporary directory exists:
Usage
checkarg_tempdir(tmp_dir)
Checks time zone, setting default if needed:
Description
Checks time zone, setting default if needed:
Usage
checkarg_time_zone(time_zone)
Retrieve a data frame containing survey column mapping
Description
Retrieve a data frame containing survey column mapping
Usage
column_map(surveyID)
Arguments
surveyID |
A string. Unique ID for the survey you want to download.
Returned as |
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)
Construct a header to send to Qualtrics API
Description
Construct a header to send to Qualtrics API
Usage
construct_header(API_TOKEN)
Arguments
API_TOKEN |
API token. Available in your Qualtrics account (see: https://api.qualtrics.com/) |
Create properly-formatted JSON payload for API calls. Removes NULLS
Description
Create properly-formatted JSON payload for API calls. Removes NULLS
Usage
create_raw_payload(...)
Value
JSON file with options to send to API
Downloads response data from location obtained from fetch_survey_progress (extracting from .zip file)
Description
Downloads response data from location obtained from fetch_survey_progress (extracting from .zip file)
Usage
export_responses_filedownload(surveyID, fileID, tmp_dir)
Arguments
surveyID |
survey ID |
fileID |
file ID from fetch_survey_progress |
tmp_dir |
temporary directory to use |
Initiate a request to the export-responses API endpoint
Description
Initiate a request to the export-responses API endpoint
Usage
export_responses_init(surveyID, body)
Arguments
surveyID |
ID of survey whose responses are being pulled |
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.
Monitor progress from response request download, then obtain file download location
Description
Monitor progress from response request download, then obtain file download location
Usage
export_responses_progress(surveyID, requestID, verbose = FALSE)
Arguments
surveyID |
ID of survey whose responses are being pulled |
requestID |
exportProgressId from https://api.qualtrics.com/37e6a66f74ab4-get-response-export-progress |
verbose |
See |
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.
Runs 3-part request to export-responses endpoint, downloading and unzipping file
Description
Runs 3-part request to export-responses endpoint, downloading and unzipping file
Usage
export_responses_request(surveyID, body, verbose = TRUE, tmp_dir)
Arguments
surveyID |
ID of the survey to be downloaded |
body |
payload/body of API request containing desired params |
verbose |
give verbose response |
tmp_dir |
temporary directory for zip file |
Extract column map from survey data download
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
respdata |
Response data including a column map dataframe as an attribute |
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)
Download complete survey description using the Qualtrics v3 "Get Survey" API endpoint.
Description
Download complete survey description using the Qualtrics v3 "Get Survey" API endpoint.
Usage
fetch_description(surveyID, elements = NULL, legacy = FALSE, ...)
Arguments
surveyID |
A string. Unique ID for the survey you want to download. Returned as "id" by the all_surveys function. |
elements |
A character vector. Lists elements of survey definition to be
maintained. Possible elements are "metadata", "surveyoptions", "flow",
"blocks", "questions", "responsesets", and/or "scoring" (case-insensitive).
If |
legacy |
Logical. If TRUE, will use older Get Survey API endpoint via a call to legacy function metadata. |
... |
Additional options, only used when |
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)
Download distribution history data for a distribution from Qualtrics
Description
Download distribution history data for a distribution from Qualtrics
Usage
fetch_distribution_history(distributionID)
Arguments
distributionID |
String. Unique distribution ID for the distribution history you want to download. |
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)
Download distribution data for a survey from Qualtrics
Description
Download distribution data for a survey from Qualtrics
Usage
fetch_distributions(surveyID)
Arguments
surveyID |
String. Unique survey ID for the distribution data you want to download. |
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)
Fetch a unique Qualtrics survey ID based on survey name in the Qualtrics UI
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
.data |
Data frame of active surveys created by the function
|
survey_name |
String. Name of the survey as it appears in the Qualtrics
UI. Must be unique to be passed to |
partial_match |
Boolean. Will match all surveys containing the exact string provided. Defaults to FALSE, which matches against the entire name. |
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)
Download a mailing list from Qualtrics
Description
Download a mailing list from Qualtrics
Usage
fetch_mailinglist(mailinglistID)
Arguments
mailinglistID |
String. Unique ID for the mailing list you want to
download. Returned as |
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)
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,
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
surveyID |
String. Unique ID for the survey you want to download.
Returned as |
limit |
Integer. Maximum number of responses exported. Defaults to
|
start_date, end_date |
POSIXct, POSIXlt, or Date object, or length-1
string equivalent of form "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS". ("/" is
also acceptable in place of "-".) Only export survey responses that were
recorded within the range specified by one or both arguments (i.e.
referencing RecordedDate). Each defaults to |
time_zone |
String. Time zone to use for date/time metadata variables in
response dataframe (e.g. StartDate). Must match a time zone name from
|
include_display_order |
Logical. If |
include_metadata, include_questions, include_embedded |
Character vector.
Specify variables to include in download. Defaults to |
unanswer_recode |
Integer-like. Recode seen-but-unanswered (usually
skipped) questions using this value. Defaults to |
unanswer_recode_multi |
Integer-like. Recode seen-but-unanswered
multi-select questions (checkboxes) using this value. Defaults to value for
|
breakout_sets |
Logical. If |
import_id |
Logical. If |
label |
Logical. If |
convert |
Logical. If |
add_column_map |
Logical. Add an attribute to the returned response data
frame containing metadata associated with the response download, including
variable names, question/choice text, and Qualtrics import IDs. This column
map can be subsequently obtained using |
add_var_labels |
Logical. If |
strip_html |
Logical. If |
col_types |
Optional. This argument provides a way to manually overwrite
column types that may be incorrectly guessed. Takes a |
verbose |
Logical. If |
tmp_dir |
Path to filesystem directory. Qualtrics returns response data
in compressed (zip) form. To extract raw data, the zip file must be briefly
written to disk (the file is then promptly deleted). By default, the
system's temporary directory is used for this (see |
last_response |
Deprecated. |
force_request |
Deprecated. |
save_dir |
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.
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)
Generate URL for specific API query by type and (if appropriate) ID
Description
Generate URL for specific API query by type and (if appropriate) ID
Usage
generate_url(query, ...)
Arguments
query |
string. The specific API query desired. Generally named the
same as associated functions but without underscores, so the request for
|
... |
Named elements of URL for specific query desired, such as
|
Value
Endpoint URL to be passed to querying tools
Set proper data types on survey data.
Description
Set proper data types on survey data.
Usage
infer_data_types(data, surveyID, verbose = FALSE)
Arguments
data |
Imported Qualtrics survey |
surveyID |
ID of survey |
verbose |
Flag |
Download distribution links for a distribution from Qualtrics
Description
Download distribution links for a distribution from Qualtrics
Usage
list_distribution_links(distributionID, surveyID)
Arguments
distributionID |
String. Unique distribution ID for the distribution links you want to download. |
surveyID |
String. Unique ID for the survey you want to download. |
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)
Download metadata for a survey
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
surveyID |
A string. Unique ID for the survey you want to download. Returned as "id" by the all_surveys function. |
get |
A character vector containing any of the following: "metadata", "questions", "responsecounts", "blocks", "flow", "embedded_data", or "comments". Will return included elements. By default, the function returns the "metadata", "questions", and "responsecounts" elements. See examples below for more information. |
questions |
Character vector containing the names of questions for which you want to return metadata. Defaults to NULL (all questions). |
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)
Install Qualtrics credentials in your .Renviron file for repeated use
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
api_key |
The API key provided to you from Qualtrics formatted in quotes. Learn more about Qualtrics API keys at https://api.qualtrics.com/ |
base_url |
The institution-specific base URL for your Qualtrics account,
formatted in quotes, without the protocol (do not include |
overwrite |
If TRUE, will overwrite existing Qualtrics
credentials that you already have in your |
install |
If TRUE, will install the key in your |
report |
If TRUE, ignores other arguments and outputs credentials as a 2-element named vector. |
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)
Send httr requests to Qualtrics API
Description
Send httr requests to Qualtrics API
Usage
qualtrics_api_request(
verb = c("GET", "POST"),
url = url,
query = NULL,
body = NULL,
as = c("parsed", "raw"),
...
)
Arguments
verb |
Type of request to be sent (@seealso |
url |
Qualtrics endpoint URL created by |
query |
Optional query parameters used by some endpoints |
body |
Options created by |
as |
type of content to return, passed to |
... |
arguments passed to httr::content when parsing |
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.
Checks responses against Qualtrics response codes and returns error message.
Description
Checks responses against Qualtrics response codes and returns error message.
Usage
qualtrics_response_codes(res)
Arguments
res |
results object from httr |
Read a CSV file exported from Qualtrics
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
file_name |
String. A CSV data file. |
strip_html |
Logical. If |
import_id |
Logical. If |
time_zone |
String. A local timezone to determine response date values.
Defaults to |
legacy |
Logical. If |
add_column_map |
Logical. If |
add_var_labels |
Logical. If |
col_types |
Optional. This argument provides a way to manually overwrite
column types that may be incorrectly guessed. Takes a |
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()))
Retrieve a data frame containing question IDs and labels
Description
Retrieve a data frame containing question IDs and labels
Usage
survey_questions(surveyID)
Arguments
surveyID |
A string. Unique ID for the survey you want to download.
Returned as |
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)
Convert multiple choice questions to ordered factors
Description
Convert multiple choice questions to ordered factors
Usage
wrapper_mc(data, question_meta)
Arguments
data |
Imported Qualtrics survey |
question_meta |
Question metadata |