Skip to content

IDinsight/surveycto-python

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

75 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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 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