Python library to download data collected on SurveyCTO data collection app using SurveyCTO REST API.
- Python version >= 3
pip install pysurveyctoSurveyCTOObject(server_name,
username,
password)Parameters:
- server_name (str): SurveyCTO server name
- username (str): SurveyCTO login username
- password (str): SurveyCTO login password
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 parameters
get_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 format
get_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 format
get_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 content
get_form_definition(form_id)
Fetch form's definition from SurveyCTO
Parameters:
- form_id (str): The form_id of the SurveyCTO form.
Returns: The form definition in JSON format
get_deployed_form_version(form_id)
Fetch version of deployed form from SurveyCTO
Parameters:
- form_id (str): The form_id of the SurveyCTO form.
Returns: The form version as a string
import pysurveycto scto = 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 groups
scto.get_form_data(form_id, shape='long', repeat_groups=false)
- Get a wide csv with line breaks replaced with space with only pending-review submissions
scto.get_form_data(form_id, line_breaks=' ', review_status=['pending'])
- Get a wide json
scto.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 CompletionDate
key_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 space
scto.get_form_data(dataset_id, line_breaks=' ')
- Get a media file attachment and save to file
data = scto.get_attachment(url) f = open(file_name, 'wb') f.write(data) f.close()
- Get form definition and save to excel file
data = 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 version
version = scto.get_deployed_form_version(form_id)