Interacting with SurveyCTO using Python
Project description
Python library to download data collected on SurveyCTO data collection app using SurveyCTO REST API.
Table of Contents
Installation
Prerequisites
Python version >= 3
Install Package
pip install pysurveycto
Usage
Initialize SCTO Object
SurveyCTOObject(server_name,
username,
password)
Parameters:
server_name (str): SurveyCTO server name
username (str): SurveyCTO login username
password (str): SurveyCTO login password
Methods:
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
Use Cases
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)
License
SCTO API Options
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pysurveycto-0.0.14-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 090994c041e63ef1aaa0c7232befe860aa5d28d46a1987941441d4a7cef45749 |
|
MD5 | ffc857341ba7838c47f30831e7780b88 |
|
BLAKE2b-256 | b1b4b56b8ea045127a9ff37ca6f023f679f9e86a9f0b421a845027d8bcbebd61 |