*! version 0.1.0 20feb2019

Title

qualtricsload -- Download survey results from Qualtrics server and optionally convert to Stata dataset

Syntax

qualtricsload
survey_id
[, options]

Main

apitoken(token) Qualtrics API token

datacenter(dsid) Qualtrics datacenter identifier

saving(fn [, replace]) Save output dataset as fn; default is the name of the survey in Qualtrics

replace Replace existing dataset (redundant with saving() suboption)

stcmd Convert downloaded dataset to Stata format using Stat-Transfer (if installed)

Qualtrics API options

format(data_format) Format for downloaded dataset. Default is 'spss'

nodisplayorder Do not include display-order (randomization) variables

timezone(timezone_id) Time zone for date/time variables

startdate(datetime) Only export responses recorded after the specified date.
See Dates and Times for more information on the date and time format

enddate(datetime) Only exports responses recorded before the specified date.

newline(string) Specify newline delimiter for the export (only applies XXX); default is '\n'

comma Use a comma as a decimal separator instead of a period

uselabels Instead of exporting the recode value for the answer choice, export the text of the answer choice. For more information on recode values, see
Recode Values

seenunansrecode(string) Recode seen but unanswered questions with this value

multiunansrecode(string) Recode seen but unanswered choices for multi-select questions. Default is to use value in seenunansrecode()

Description

qualtricsload downloads survey responses directly from Qualtrics using the Qualtrics API and optionally translates the dataset to Stata format.

Your Qualtrics account must have API access enabled, and you must obtain an API token. See
Generating an API Token
for instructions on checking access and obtaining a token from Qualtrics.

You also need to know your Qualtrics datacenter id, which is usually the two or three letters and a number that preceed "qualtrics" in the URL for your Qualtrics login. See
Locating the Datacenter ID for help finding it.

There are several ways to specify your API Token and Datacenter ID. The program will look for them in the following locations (in this order):
(1) as options with each use of the qualtricsload command;
(2) by setting system environment variables QUALTRICS_API_TOKEN and QUALTRICS_DATA_CENTER; or
(3) in a configuration file whose location is specified by environment variable QUALTRICS_CONFIG_FILE.
The configuration file should be a plain-text file containing the following lines:

QUALTRICS_API_TOKEN = api token value

QUALTRICS_DATA_CENTER = datacenter id value

Options

Main

apitoken(token) specifies your Qualtrics API Token.
Although you can specify your API key using this option, long term it is better practice to keep it instead in a configuration file as described above.
This increases security (your API key is equivalent to your Qualtrics password), and also allows for easier updating if you regenerate your API key.

datacenter(dsid) specifies your Qualtrics datacenter identifier.
As with the API key, use of qualtricsload is simplified if you specify this in a configuration file as described above.

saving(fn [, replace]) specifies the name of the output dataset. By default this will be the same as the name of the survey in Qualtrics.
If stcmd is specified, this will be a Stata dataset; otherwise it will have the format specified in the format option.

replace indicates that an existing file may be replaced. This is equivalent to the replace suboption of the saving() option.

stcmd indicates that the downloaded dataset be converted to Stata format using Stat-Transfer.
This option requires that Stat-Transfer be installed and the
stcmd Stata command is installed and configured.
See ssc describe stcmd.

Qualtrics API options

These options correspond to the API options described here:
https://api.qualtrics.com/reference/create-response-export-new.

format(data_format) specifies the format for the downloaded dataset.
Default is 'spss'; other options are 'csv', 'tsv', 'json', or 'ndjson'.
If the stcmd option is specified, this option is ignored:
the dataset is downloaded to a temporary file in SPSS format and converted to Stata.

t nodisp:layorder} indicates that "display order" variables should not be included.
For surveys that include randomization, these variables indicate which elements were displayed in what order. By default these variables are included in the download.

timezone(timezone_id) indicates the time zone for date/time variables (including StartDate, EndDate, RecordedDate).
By default the program will attempt to use Java system's default time zone, which should be your local time zone.

startdate(datetime) indicates that only responses recorded (i.e., RecordedDate) after the specified date should be included.
Specify datetime as "yyyy-mm-ddThh:mm:ss±HH:MM", where ±HH:MM is the offset from UTC;
e.g., "2019-01-17T14:47:00-05:00" would indicate 2:47pm on January 17, 2019 in the Eastern US time zone (i.e., UTC minus 5 hours).
See Dates and Times for more information on the date and time format in Qualtrics,
or https://en.wikipedia.org/wiki/ISO_8601 for far more than you ever wanted
to know about the ISO 8601 standard for representing dates and times.

enddate(datetime) indicates that only responses recorded before the specified date should be included.

newline(string) specify a newline delimiter for the export; default is '\n'.

comma indicates that a comma be used as the decimal separator instead of a period. This has no effect for spss/stcmd downloads.

uselabels indicates that the text of the answer choices, rather than the numerical values. Has no effect for spss/stcmd downloads.
For more information on recode values, see
Recode Values

seenunansrecode(string) indicates that "seen but unanswered" questions should be recoded with this value, rather than system missing.
Must be an integer between -2,147,483,648 and 2,147,483,647;
due to limitations in the Qualtrics export, it may not be an extended missing value.

multiunansrecode(string) indicates that "seen but unanswered" multi-select questions should be recoded with this value,
rather than system missing or the value specified by seenunansrecode().

Remarks

To get started, you should:

(1) Determine whether your Qualtrics account allows API access and obtain your API Token.
To do so, click on the silhouette in the top-right corner of your account; Select "Account Settings"; Click "Qualtrics IDs" on the navigation bar; in the box labeled "API", click "Generate Token".
Important note: if you already have an API token, do not re-generate it unless you want to invalidate the existing token.
See
Generating an API Token.

(2) Determine the survey ID of the Qualtrics survey you want to download. Survey IDs are available from the "Qualtrics IDs" page, or can be inferred from the URL used to edit or take the survey; they have the format SV_xxxxxxxxxxxxxxx, where 'xxxxxxxxxxxxxxx' is a random set of letters and numbers.

(3) Download your data!

Examples

Download Qualtrics survey SV_BD08KxeNaYZVaX2 and convert to Stata dataset using Stat-Transfer, using the Qualtrics study name as the filename:

. qualtricsload SV_BD08KxeNaYZVaX2 , stcmd

Download Qualtrics survey SV_JvsVR3qTrHbPxP4, specifying Qualtrics API Token and datacenter, and convert to Stata dataset named "mydata.dta":

. qualtricsload SV_JvsVR3qTrHbPxP4 , stcmd apitoken(csxGqLIRzHmogKP2UjPwfOxRsiTk002jvvgFly3t) datacenter(az1) saving(mydata, replace)

Copyright

See qualtricsload copyright.

Author

Nicholas J. G. Winter
Department of Politics
University of Virginia
nwinter [at] virginia.edu