Welcome to SimpleQualtrics 1.0.3

Introduction

SimpleQualtrics is a stand-alone simple API to access the Qualtrics APIs directly, handling all of the Qualtrics web-specific protocols in a robust manner and answering data structures that are easy to process in Python.

Specifically, it implements separating credentials from code, configuration handling, choice of API server, practical error handling, call timeouts, call logging, and Python-friendly decoding of Qualtrics response formats and protocols.

Installation

pip install SimpleQualtrics

See https://pypi.org/project/SimpleQualtrics/

Using SimpleQualtrics

There are many Qualtrics APIs in V3, but they use standard calling and response patterns.

So SimpleQualtrics provides full coverage of all the Qualtrics APIs by requiring the caller to pass the API call strings and parameters. It provides Pythonic processing, chaining of multiple associated requests and file-access requests, logging, timeouts, and error handling using exceptions.

Example usage:

# Import as modules:
import SimpleQualtrics
import pandas as pd

# Include the following to log calls and errors to stderr:
import logging
logging.basicConfig(level=logging.INFO)

# Initialise from configuration file:
q=SimpleQualtrics.Session(yaml='QualtricsCredentials.yaml')

# Get a simple structure:
myName = q.get('whoami')['firstName']

# Get details of all mailing lists as a Pandas DataFrame:
mailingLists=pd.DataFrame(q.getMultiple('mailinglists'))

# Create a new mailing list, using our user ID as library ID:
newListId=q.postCreate('mailinglists', {'name':'New List', 'libraryId': q.get('whoami')['userId']})

# Delete that mailing list:
q.delete('mailinglists/'+newListId)

# Get survey results:
responsesDataFrame=pd.read_csv(q.fileFromPost('surveys/SV_999999999999999/export-responses',{'format':'csv'}))

Try https://api.qualtrics.com/instructions/docs/Instructions/limits.md as a starting point for the documentation of the Qualtrics APIs.

If your Qualtrics requirements are not handled by the higher level functions (get, post, put, delete, etc.), use the call function. It has similar semantics to requests.request, but adds Qualtrics credentials, errors, timeouts and logging. E.g.:

responseContentFromDifferentCall = q.call('POST', 'different', json={'some': 'parameters'}).content

The library uses standard Python logging, making a single INFO log entry for each outgoing call, and an ERROR log entry where exceptions are thrown.

SimpleQualtrics Configuration

Credentials can be held in a yaml file. Example contents might be:

token: 75STYGWg2nyQXTE46Ov7BDVSslFkt6TSkzxxxx # Your API token
dataCenter: fra1 # Your data centre
fileCreationTimeout: 60 # seconds.
somethingElse:avalue # ...  any other relevant configuration that might be convenient to put in this file.

The required configuration parameters are:

token: the Qualtrics API token
dataCenter: the Qualtrics center ID to use

Optional configuration parameters are:

timeout: the timeout in seconds for calls, default 30;
fileCreationTimeout: the timeout in seconds for file creation, default same as the timeout above.
fileCreationPollIntervalMillis: the file creation polling interval in milliseconds, default 500.

See https://help-nv.qsrinternational.com/12/win/v12.1.96-d3ea61/Content/files/qualtrics-api-token.htm to find the tokens.

Code Documentation

class Session(**kwargs)

This class handles simple access to Qualtrics V3 APIs. It implements credentials, configuration handling, choice of API server, practical error handling, call timeouts, call logging, and Python-friendly decoding of Qualtrics response formats and protocols.

Keyword parameters are added as configuration items to the configuration database, except:

SimpleQualtrics(yaml='filename.yaml')

loads configuration from the given file.

The required configuration parameters are:

token: the Qualtrics API token
dataCenter: the Qualtrics center ID to use)

call(action, url, **kwargs)

Make an https call to url, with the appropriate Qualtrics headers, logging and timeout, answering a requests.Result object.

Parameters

action (String) – A requests action, such as ‘POST’
url (String) – Either the relative path for API request, or the full path starting ‘http’…
kwargs (Dictionary of string pairs) – keyword parameters to pass with the request

Return type

requests.Result

Raises

requests.RequestException – For any http error, timeout, or QualtricsError.

Use json={someParameters} to pass parameters to a POST or PUT

config(item, default=None)

Answer the configuration entry for the given item, else a default if provided

Parameters

item (String) – The configuration item
default (String) – Default value if the item is not in the configuration database

Return type

String

Raises

KeyError – if item is not found and no default is present

delete(relPath)

Call DELETE for the given path

Parameters: relPath (String) – The relative path for the API request
Raises: requests.RequestException –

fileFromPost(relPath, parameters)

Answer a filestream containing the result of the given request for a responses file. Supports both legacy and newer downloading of responses.

Parameters

relPath (String) – The relative path for the initial API request
parameters (Dictionary of string pairs) – keyword parameters to pass with the initial request

Return type

IOStream

Raises

requests.RequestException –

Note that the filestream supports seek(), which allows it to be read more than once.

get(relPath)

Make a GET request that answers a single structure as a Python dictionary.

Parameters: relPath (String) – The relative path for the API request
Return type: Dictionary
Raises: requests.RequestException –

getMultiple(relPath)

Make a GET request that returns an array of structures, implementing paging if the API uses it.

Parameters: relPath (String) – The relative path for the initial API request
Return type: List of Dictionaries.
Raises: requests.RequestException –

Use the return value as constructor parameter to create a Pandas DataFrame.

post(relPath, parameters)

Make a POST request that returns a single structure as a Python dictionary.

Parameters

relPath (String) – The relative path for the API request
parameters (Dictionary of string pairs) – keyword parameters to pass with the request

Return type

Dictionary

Raises

requests.RequestException –

postCreate(relPath, parameters)

Do the specified post, answering the string id of the object created where this is the only entry in the results or where it contains one of the possibleIdFields fields, else None.

Parameters

relPath (String) – The relative path for the API request
parameters (Dictionary of string pairs) – keyword parameters to pass with the request

Return type

String or None

Raises

requests.RequestException –

put(relPath, parameters)

Call PUT for the given path and parameters

Parameters

relPath (String) – The relative path for the API request
parameters (Dictionary of string pairs) – keyword parameters to pass with the request

Raises

requests.RequestException –

exception QualtricsError(*args, **kwargs)

Bases: RequestException

The Qualtrics server returned an error

Initialize RequestException with request and response objects.