Skip to main content

qualtrics-utils

Utilities for qualtrics surveys. Get and sync survey responses, generate codebooks, & c.

Quickstart 🚀

This project requires Python ^3.10 to run.

via poetry

Install poetry, then run

poetry install

And you're done.

surveys

Exporting

Example (get a survey's responses, convert to a pandas DataFrame):

from qualtrics_utils import Surveys

surveys = Surveys(api_token=QUALTRICS_API_TOKEN)

exported_file = surveys.get_responses_df(
    survey_id=SURVEY_ID
)
df = exported_file.data

Survey's can be exported to a variety of formats, including:

  • .csv
  • .xlsx
  • .json

And with a variety of parameters. Please see the ExportCreationRequest documentation herein

sync

Perhaps one of the more useful features hereof is the ability to sync survey responses to the following services:

  • Google Sheets
  • MySQL

Future services will include:

  • PostgreSQL
  • MongoDB
  • AWS S3

Syncing can either be leveraged as a standard python module, or as a CLI tool.

CLI

Execute the help command to see the available options:

python -m qualtrics_utils.sync --help

See also the config.example.toml for an example configuration file.

Module

Simply import sync_* from the qualtrics_utils.sync module, and execute the function with the appropriate arguments.

Syncing information

The process is fairly straightforward:

  1. Ensure that the service has two "tables", or datastores for:
    • Survey responses: This defaults to the input base name (defaults to the survey ID) + _responses
    • Survey export statuses: This defaults to the input base name (defaults to the survey ID) + _status
  2. Export the survey responses to the service
  3. Update the survey export statuses to reflect the export

This will allow for a sync to pick up where it left off, only exporting newly found responses. Please note, if a first time sync contains enough survey responses to exceed the service's limits (~1.8 GB), the sync will fail. Please see the Qualtrics documentation for more information.

For example, in google sheets:

from qualtrics_utils import Surveys, sync_sheets
import pandas as pd

# Survey ID or URL
survey_id = ...
# Sheet URL
responses_url = ...

# dict of extra survey arguments for the export creation request
survey_args = ...

sheets = Sheets()

def post_processing_func(df: pd.DataFrame) -> pd.DataFrame:
    # Do some post processing of the responses before syncing here
    return df

sync_sheets(
    survey_id=survey_id,
    surveys=surveys,
    response_post_processing_func=post_processing_func,
    sheet_name=table_name,
    sheet_url=responses_url,
    sheets=sheets,
    **survey_args,
)

Codebook mapping

generate.py

Takes the exported .qsf file from Qualtrics and generates a codebook mapping question IDs to question text and answer choices. The output is a JSON file containing a list of dictionaries.

Example row:

{
        "question_number": "Q5.10",
        "question_string": "What is your role at this school?",
        "answer_choices": "..."
},

map_columns.py

Takes a codebook mapping (generated by the above function) and creates conditional statements to map the question columns into valid Tableau or SQL code. Used to create a singular question column in the above formats when there are multiple questions in a single question block (e.g. multiple Likert scale questions).

OpenAPI client

To handle the majority of the qualtrics API calls, we use the publicly available OpenAPI spec, found on the qualtrics API docs website

The OpenAPI spec is fed to openapi-python-client, where it's used to generate a python client(s) for the qualtrics API. These clients (for each of the utilized APIs) come bundled and pre-generated as-is, but to create them anew, one can execute the create_api_client.py script. This will re-generate the clients and place them in the qualtrics_utils directory. Occasionally, the OpenAPI spec is broken and mis-validated from Qualtrics; regenerate at your own risk.

Metadata

Release files for qualtrics-utils 1.0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qualtrics-utils 1.0.5
File Size Uploaded Provenance Actions
qualtrics_utils-1.0.5.tar.gz 61.1 kB Without provenance Details for qualtrics_utils-1.0.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qualtrics-utils 1.0.5
File Interpreter ABI Platform Actions
qualtrics_utils-1.0.5-py3-none-any.whl Python 3 none any Details for qualtrics_utils-1.0.5-py3-none-any.whl

Total release size: 189.7 kB

Release files / qualtrics_utils-1.0.5.tar.gz

Download URL qualtrics_utils-1.0.5.tar.gz
Size 61.1 kB
Tags Source
SHA-256 checksum
How to use checksums
9ae73295f29ece6130beb3d91dc756ca4ac13bafe2bd79ce7cd1f6a5639b585c
BLAKE2b-256 checksum
How to use checksums
999e5009cece630e2950e928edc8dd4a8aa9004fbd15a9d329ede593db87cf57
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.12.7 Darwin/24.1.0

Release files / qualtrics_utils-1.0.5-py3-none-any.whl

Download URL qualtrics_utils-1.0.5-py3-none-any.whl
Size 128.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a5766157c8c5bcca2335983237206365f2e84a72e3090a468f5d5801031d59fa
BLAKE2b-256 checksum
How to use checksums
d8ff7d4429704671f43211c5e3c5170ed0ebdbf6fdf17a1146b26028e1ce0b79
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.12.7 Darwin/24.1.0

Security for qualtrics-utils 1.0.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page