help for sctoapi

Title

sctoapi -- downloads SurveyCTO data via API

Syntax

sctoapi formids [if] [in], server(servername) username(username)
password(password) date(unixtimestamp) outputfolder(folder_path)
[key(file_path)] [media(varlist)] [dtafile]

Alternatively, type db sctoapi to run the command via a dialog box or click here.

server(servername) Specifies the SurveyCTO Server name.

username(username) Specifies the SurveyCTO Username.

password(password) Specifies the SurveyCTO password.

date(unixtimestamp) Specifies the date (UTC time) from which data collected will be downloaded. It can be
a timestamp in seconds or milliseconds.

outputfolder(folder_path) Destination folder of export files.

key(file_path) Specifies the file of the Private Key. [For
encrypted forms]

media(varlist) Specifies the media variables to export.

dtafile If specified, a .dta file will be generated and saved in the Destination folder.

Description

sctoapi downloads SurveyCTO data in JSON format
via the API
(you'll need a SurveyCTO account to see the content of the link). The data is then converted and saved
in CSV and DTA (optional) format. Optionally, it also downloads media files which are saved in
an `outputfolder' subfolder named 'media' - you'll then be able to run the sctomedia command
to rename and relocate your media files, if needed. For a more user-friendly way to run the sctoapi command, and
to ensure that the password is hidden and not saved in any log, you can use the dialog box for the
command (type db sctoapi or click here).

Options

server(servername) specifies the name of the SurveyCTO server where the form data is stored.

username(username) specifies a username with permission to download data from the SurveyCTO server specified.

password(password) specifies the password of the username.

date(unixtimestamp) specifies the date parameter of the request. It should be specified in UTC time and can follow
one of the following formats: 1) A timestamp in seconds (e.g. 1444694400), 2) A timestamp in milliseconds (the value is
treated in milliseconds when 13 (or more) digits are specified - e.g. 1444694400000). 3) A specific string
representation (e.g. Oct%2013%2C%202015%2000%3A00%3A00%20AM). Convert your dates into unix time stamps with an
online converter or bypass and request all data by specifying 0, but be mindful
of the rate limiting. For more information, visit
our API documentation
(you'll need a SurveyCTO account to see the content of the link).

outputfolder(folder_path) specifies the main destination folder path. If media is specified, media files will be saved
in the sub-folder 'media' within the output folder.

key(file_path) specifies the file path of the Private Key. This is only required
for encrypted forms.

media(varlist) specifies the SurveyCTO form media fields you want to download and save
in "`outputfolder'/media", including
audio audits,
text audits,
images,
audio,
and video.

dtafile saves a .dta file in the output folder, if specified.

Examples

Note that only Users with permission to 'Download Form data' will be able to run this command successfully.

All Examples will use the following local as folder path:

. local destination "C:/Users/username/Documents"

Example 1

sctoapi testform, server(scto) username(support@surveycto.com) password(1234) date(1546344000) output(`destination')

In this example, the sctoapi command is being run to download the data from the form with ID 'testform', deployed in
the server 'scto'. We're using the credentials of the user 'support@surveycto.com' with password '1234'. This code
will trigger the following actions:

. Fetch testform data submitted after Jan 1, 2019 in WIDE format

. Save the data in `destination' in JSON and CSV format

Example 2

sctoapi testform, server(scto) username(support@surveycto.com) password(1234) date(1546344000) output(`destination') media(textaudit) dtafile

In this example, the sctoapi command is being run to download the data from the form with ID 'testform', deployed
in the server 'scto'. We're using the credentials of the user 'support@surveycto.com' with password '1234'. This code
will trigger the following actions:

. Fetch testform data submitted after Jan 1, 2019 in WIDE format

. Save the data in `destination' in JSON, CSV and DTA format

. Fetch media files collected in the field named 'textaudit' and save them in `destination'/media

Example 3

sctoapi encrypted_form, server(scto) username(support@surveycto.com) password(1234)
date(1546344000) output(`destination') key(C:\Users\username\Downloads\Encrypted_Form_PRIVATEDONOTSHARE.pem)

In this example, the sctoapi command is being run to download the data from the form with ID 'encrypted_form', deployed
in the server 'scto'. We're using the credentials of the user 'support@surveycto.com' with password '1234'. This code
will trigger the following actions:

. Fetch encrypted_form data submitted after Jan 1, 2019 in WIDE format

. Decrypt encrypted_form data using the private key saved in the
file "C:\Users\username\Downloads\Encrypted_Form_PRIVATEDONOTSHARE.pem".

. Save the data in `destination' in JSON and CSV format

Author

This command is the SurveyCTO version of a pre-existing resource for Stata users created by Innovations
for Poverty Action (IPA). Both resources achieve the same aims, but this version has been tailored for more general use, compared
to the specific requirements of IPA projects. You can see this command's repository
on Github.