Package: pysurveycto
Python library to download data collected on SurveyCTO data collection
app using SurveyCTO REST API.Table of ContentsInstallationUsageUse CasesLicenseSCTO API OptionsInstallationPrerequisitesPython version >= 3Install PackagepipinstallpysurveyctoUsageInitialize SCTO ObjectSurveyCTOObject(server_name,username,password)Parameters:server_name(str): SurveyCTO server nameusername(str): SurveyCTO login usernamepassword(str): SurveyCTO login passwordMethods:get_form_data(form_id,format='csv',shape='wide',oldest_completion_date=None,review_status=None,repeat_groups=None,line_breaks=None,key=False)Fetch SurveyCTO form data in json or csv formats.Parameters:form_id(str): The form_id of the SurveyCTO form.format(str, optional): The format of the returned data. Allowed values are: json, csv(default).shape(str, optional): The shape of the returned data. Allowed values are: wide(default), long. shape=’long’ can only be specified when returning data in csv format.oldest_completion_date(datetime.date or datetime.datetime object, optional): Return only the form submissions where CompletionDate is greater than or equal to the given date (in UTC). Can only be specified when returning data in json format.review_status(list, optional): Return only the form submissions with given review status. Allowed values in the list are: approved(default), rejected, pending. This option is only applicable for forms using the “Review and Corrections” workflow on the SurveyCTO web console.repeat_groups(bool, optional): Return a dictionary object containing the main form data along with the repeat groups. Can only be specified when returning long data, in which case it will default to true.line_breaks(str, optional): Replace line breaks in the csv data with some other character.key(str, optional): The private key to decrypt form data in binary/string. This can be used only for json extracts without a review_status parameter.Returns:Form data in json or csv (wide or long) format depending on the parametersget_repeatgroup(form_id,repeat_group_name,review_status=None,line_breaks=None)Fetch SurveyCTO form’s repeat group data.Parameters:form_id(str): The form_id of the SurveyCTO form.repeat_group_name(str): Form’s repeat group name.review_status(list, optional): Return only the form submissions with given review status. Allowed values in the list are: approved(default), rejected, pending. This option is only applicable for forms using the “Review and Corrections” workflow on the SurveyCTO web console.line_breaks(str, optional): Replace line breaks in the csv data with some other character.Returns:Repeat group data in csv formatget_server_dataset(dataset_id,line_breaks=None)Fetch SurveyCTO server dataset data.Parameters:dataset_id(str): The server dataset id of the SurveyCTO dataset.line_breaks(str, optional): Replace line breaks in the csv data with some other character.Returns:Server dataset data in csv formatget_attachment(url,key=False)Fetch form’s file attachments like media/audio/images from SurveyCTO.Parameters:url(str): The URL to the attached file.key(str, optional): The private key to decrypt an encrypted attachment in binary/string.Returns:The url contentget_form_definition(form_id)Fetch form’s definition from SurveyCTOParameters:form_id(str): The form_id of the SurveyCTO form.Returns:The form definition in JSON formatget_deployed_form_version(form_id)Fetch version of deployed form from SurveyCTOParameters:form_id(str): The form_id of the SurveyCTO form.Returns:The form version as a stringUse Casesimportpysurveyctoscto=pysurveycto.SurveyCTOObject(server_name,username,password)Get a wide csv:scto.get_form_data(form_id)Get a long csv with all repeat groups (Returns a dictionary with repeat group names as keys and csv data for the repeat groups as values)scto.get_form_data(form_id,shape='long')Get a long csv without repeat groupsscto.get_form_data(form_id,shape='long',repeat_groups=false)Get a wide csv with line breaks replaced with space with only pending-review submissionsscto.get_form_data(form_id,line_breaks=' ',review_status=['pending'])Get a wide jsonscto.get_form_data(form_id,format='json')Get a wide json with forms completed after a given date (exclusive)date_input=datetime.datetime(2020,1,12,13,42,42)scto.get_form_data(form_id,format='json',oldest_completion_date=date_input)Get a wide json for encrypted form starting after a given CompletionDatekey_data=open('<path to keyfile>','rb')scto.get_form_data(form_id,format='json',oldest_completion_date=my_datetime,key=key_data)Get a server dataset with line breaks replaced with spacescto.get_form_data(dataset_id,line_breaks=' ')Get a media file attachment and save to filedata=scto.get_attachment(url)f=open(file_name,'wb')f.write(data)f.close()Get form definition and save to excel filedata=scto.get_form_definition(form_id)questions_df=pd.DataFrame(data["fieldsRowsAndColumns"][1:],columns=data["fieldsRowsAndColumns"][0],)choices_df=pd.DataFrame(data["choicesRowsAndColumns"][1:],columns=data["choicesRowsAndColumns"][0],)settings_df=pd.DataFrame(data["settingsRowsAndColumns"][1:],columns=data["settingsRowsAndColumns"][0],)writer=pd.ExcelWriter(file_name,engine="openpyxl")questions_df.to_excel(writer,sheet_name="survey",index=False)choices_df.to_excel(writer,sheet_name="choices",index=False)settings_df.to_excel(writer,sheet_name="settings",index=False)writer.save()Get form versionversion=scto.get_deployed_form_version(form_id)LicenseThe MIT License (MIT)SCTO API OptionsSCTO API Documentation