Skip to main content

Interacting with SurveyCTO using Python

Project description

pysurveycto

Python library to download survey data collected on SurveyCTO data collection app via the 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, 
                  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.
    • date (datetime.date or datetime.datetime object, optional): Return only the form submissions where CompletionDate is greater than 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 linebreaks 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 repeatgroup 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 linebreaks 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 linebreaks 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 encrupted attachment in binary/string.

    Returns: The url content


Use Cases

import pysurveycto
scto = SurveyCTOObject(server_name, username, password)
  • Get a wide csv

    scto.get_form_data(form_id)
    
  • Get a long csv with repeat groups

    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 linebreaks 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 on given date

    date_input = datetime.datetime(2020, 1, 12, 13, 42, 42)
    scto.get_form_data(form_id, format=json, 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, date=my_datetime, key=key_data)
    
  • Get a server dataset with linebreaks 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()
    

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.2.tar.gz (8.4 kB view hashes)

Uploaded Source

Built Distribution

pysurveycto-0.0.2-py3-none-any.whl (8.8 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