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

  • 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

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.15.tar.gz (11.3 kB view details)

Uploaded Source

Built Distribution

pysurveycto-0.0.15-py3-none-any.whl (9.9 kB view details)

Uploaded Python 3

File details

Details for the file pysurveycto-0.0.15.tar.gz.

File metadata

  • Download URL: pysurveycto-0.0.15.tar.gz
  • Upload date:
  • Size: 11.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.7

File hashes

Hashes for pysurveycto-0.0.15.tar.gz
Algorithm Hash digest
SHA256 496b24abe1a881bdd81aa8dce504692d1a192de7a233294c6db17d842def642a
MD5 b7d988137c42c417ebd29f9b543c912d
BLAKE2b-256 4f05410fa2652a9056895657993585f6c483e7473d41fb6a8f79c13825f876df

See more details on using hashes here.

File details

Details for the file pysurveycto-0.0.15-py3-none-any.whl.

File metadata

File hashes

Hashes for pysurveycto-0.0.15-py3-none-any.whl
Algorithm Hash digest
SHA256 c9067b852542384d9212291129c379f6684cb470515887677f99c8dd70060a20
MD5 fd5f6b2ad35e201e2bfc915463bf1543
BLAKE2b-256 3bdaeef9f801296d1881064fe1fe5a068b659f908fa7d31677a82e1c39115f0f

See more details on using hashes here.

Supported by

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