pysurveycto
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 pysurveyctoUsage
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
list_forms()Fetch all form_id’s available in your SurveyCTO server
Parameters: - None
Returns: list of dictionaries, each dictionary containing information for each form on server
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
Release files for pysurveycto 0.0.15
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 |
|---|---|---|---|---|
| pysurveycto-0.0.15.tar.gz | 11.3 kB | Without provenance | Details for pysurveycto-0.0.15.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pysurveycto-0.0.15-py3-none-any.whl | Python 3 | none | any | Details for pysurveycto-0.0.15-py3-none-any.whl |
Total release size: 21.1 kB
Release files / pysurveycto-0.0.15.tar.gz
| Download URL | pysurveycto-0.0.15.tar.gz |
|---|---|
| Size | 11.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
496b24abe1a881bdd81aa8dce504692d1a192de7a233294c6db17d842def642a
|
|
BLAKE2b-256 checksum How to use checksums |
4f05410fa2652a9056895657993585f6c483e7473d41fb6a8f79c13825f876df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.7
|
Release files / pysurveycto-0.0.15-py3-none-any.whl
| Download URL | pysurveycto-0.0.15-py3-none-any.whl |
|---|---|
| Size | 9.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c9067b852542384d9212291129c379f6684cb470515887677f99c8dd70060a20
|
|
BLAKE2b-256 checksum How to use checksums |
3bdaeef9f801296d1881064fe1fe5a068b659f908fa7d31677a82e1c39115f0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.7
|
Security for pysurveycto 0.0.15
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.
