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:
- 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
- Survey responses: This defaults to the input base name (defaults to the survey ID) +
- Export the survey responses to the service
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.