Package: qualtrics-utils
qualtrics-utilsUtilities for qualtrics surveys. Get and sync survey responses, generate codebooks, & c.Quickstart 🚀This project requires Python^3.10to run.viapoetryInstall poetry, then runpoetry installAnd you're done.surveysExportingExample (get a survey's responses, convert to a pandas DataFrame):fromqualtrics_utilsimportSurveyssurveys=Surveys(api_token=QUALTRICS_API_TOKEN)exported_file=surveys.get_responses_df(survey_id=SURVEY_ID)df=exported_file.dataSurvey's can be exported to a variety of formats, including:.csv.xlsx.jsonAnd with a variety of parameters. Please see theExportCreationRequestdocumentationhereinsyncPerhaps one of the more useful features hereof is the ability to sync survey responses to the following services:Google SheetsMySQLFuture services will include:PostgreSQLMongoDBAWS S3Syncing can either be leveraged as a standard python module, or as a CLI tool.CLIExecute thehelpcommand to see the available options:python-mqualtrics_utils.sync--helpSee also theconfig.example.tomlfor an example configuration file.ModuleSimply importsync_*from thequaltrics_utils.syncmodule, and execute the function with the appropriate arguments.Syncing informationThe 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) +_responsesSurvey export statuses: This defaults to the input base name (defaults to the survey ID) +_statusExport the survey responses to the serviceUpdate the survey export statuses to reflect the exportThis 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 theQualtrics documentationfor more information.For example, in google sheets:fromqualtrics_utilsimportSurveys,sync_sheetsimportpandasaspd# Survey ID or URLsurvey_id=...# Sheet URLresponses_url=...# dict of extra survey arguments for the export creation requestsurvey_args=...sheets=Sheets()defpost_processing_func(df:pd.DataFrame)->pd.DataFrame:# Do some post processing of the responses before syncing herereturndfsync_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 mappinggenerate.pyTakes the exported.qsffile 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.pyTakes 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 clientTo handle the majority of the qualtrics API calls, we use the publicly available OpenAPI spec, found on the qualtrics API docswebsiteThe OpenAPI spec is fed toopenapi-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 thecreate_api_client.pyscript. This will re-generate the clients and place them in thequaltrics_utilsdirectory. Occasionally, the OpenAPI spec is broken and mis-validated from Qualtrics; regenerate at your own risk.