qtools

qtools is a series of tools in Python3 for connecting and interacting with the Qualtrics APIs

Table of contents

• Requirements
• Installation
• Usage

Requirements

qtools requires python 3.6 or greater. Currently, it has the following dependencies:

• openpyxl >= 2.6.3
• dotted-dict >= 1.1

Installation

The preferred installation method is to download the latest precompiled binary (currently 0.7.8) from the dist folder and install via pip:

pip install /path/to/file

Alternatively, qtools can be installed by cloning/downloading the repository and running the setup.py script with the install option

<path_to_qtools_folder>/setup.py install

Usage

Using the ExportClient class:

The ExportClient class allows interaction with (as of 0.6.7) the Survey Response Exports and Survey Definitions APIs to download and retrieve Survey response data.

To use the ExportClient class:

import qtools
ec = qtools.ExportClient(data_center='your_data_center', token='your_api_token')

data_center and token are optional arguments which specify your Qualtrics data center and API token, respectively.

These variables can either specify the data center and API tokens directly, or point to OS environment variables which hold the appropriate values

If omitted, ExportClient will attempt the following during initialization:

1. Attempt to find and use the OS environment variables Q_DATA_CENTER and Q_API_TOKEN for the data_center and token parameters, respectively
2. if step 1 fails, prompt the user for these values via password prompts

If either argument is specified, Export client will attempt the following during initialization:

1. Attempt to find an OS Environment variable by the name specifed
2. if step 1 fails, assume the user-provided value is the data center/token

The preferred usage is to create the OS environment variables Q_DATA_CENTER and Q_API_TOKEN and populate them with your data center and API token, then call the parameterless constructor:

from qtools import *
ec = ExportClient()

For instructions of locating your data center and API tokens, see https://api.qualtrics.com/docs/finding-qualtrics-ids

for instructions regarding environmental variables, see:

• windows: Oracle.com
• linux: serverlab.ca
• mac: Himanshu Aggarwal's blog

Retrieving a list of your surveys with the ExportClient class

Surveys owned by a user are retrieved with the get_survey_list method, which will return a dictionary mapping survey ID to survey name

import qtools
ec = qtools.ExportClient()
surveys = ec.get_survey_list()

Exporting survey response data with the ExportClient class

Response data can be downloaded via the export_responses method:

from qtools import *
ec = ExportClient()
ec.export_responses(out_folder="path_to_save", survey_id="qualtrics_id", file_format=Format.SPSS, 
                    report_progress=True, update_every=0.5, **kwargs)

export_responses accepts the following arguments:

• out_folder: The absolute folder in which exported responses should be saved
• survey_id: The qualtrics ID of the survey whose responses are to be exported.
• locator: A callable which returns the ID of the survey to be exported. Specify this argument if survey_id is not provided. Note that failure to specify both survey_id and locator will cause a prompt for users to input a survey ID
• file_format: Specifies the file format to be downloaded. Accepts the following values from the constants module:
  Format.CSV,
  Format.JSON,
  Format.NDJSON,
  Format.SPSS,
  Format.TSV,
  Format.XML
  
• report_progress: Specifies whether to report the progress of the export download. Default True
• update_every: Specifies how often (in seconds) to check the progress of export downloads. Default 0.5

export_responses also accepts a variety of keyword arguments as allowed by the Export API (see the 'Body Params' section of the Create Response Export API for more details on these)

Exporting Survey Definitions and Data Dictionaries/Codebooks

Survey definition data and codebooks can be downloaded with the export_survey_definition and export_codebook methods, respectively:

Exporting a Survey Definintion

from qtools import *
ec = ExportClient()
survey_def = ec.export_survey_definition(survey_id='surveyID', format=Format.JSON)

The export_survey_definition method accepts the following arguments:

• survey_id: The ID of the survey whose definition is to be exported
• locator: A callable which returns the ID of the survey to be exported. Specify this argument if survey_id is not specified
• format: The format of the data. Format.JSON for JSON data or format.TXT for text. Default Format.JSON

export_survey_definition returns either a JSON object or text (which can be converted to JSON), depending on the value provided to format

Exporting a codebook/data dictionary

from qtools import *
ec = ExportClient()
wb = ec.export_codebook(survey_id="qualtrics_id" [locator=l])

The export_codebook method accepts the following arguments:

• survey_id: The ID of the survey whose definition is to be exported
• locator: A callable which returns the ID of the survey to be exported. Specify this argument if survey_id is not specified

export_codebook returns an openpyxl.Workbook object. The resulting workbook will contain one worksheet for each block of the survey. Each worksheet will contain descriptions of the variables exported into a dataset via the Survey Response Exports API, including a variable's name, label, and value labels (if any).