Skip to main content

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

The MIT License (MIT)

SCTO API Options

SCTO API Documentation

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pysurveycto-0.0.14.tar.gz (11.0 kB view hashes)

Uploaded Source

Built Distribution

pysurveycto-0.0.14-py3-none-any.whl (9.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page