pysurveycto

Python library to download data collected on SurveyCTO data collection app using SurveyCTO REST API.

Table of Contents

• Installation
• Usage
• Use Cases
• License
• SCTO API Options

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 CompletionDate (inclusive)

  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 (inclusive)

  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

The MIT License (MIT)

SCTO API Options

SCTO API Documentation