cto_form_data: Download and Tidy SurveyCTO Form Data

In ctoclient: A Modern and Flexible Data Pipeline for 'SurveyCTO'

Download and Tidy SurveyCTO Form Data

Description

Downloads submission data from a SurveyCTO server in wide JSON format. Encrypted forms are supported via a private key. When tidy = TRUE (default), the function uses the form's XLSForm definition to convert variables to appropriate R types, drop structural fields, and organize columns for analysis.

Usage

cto_form_data(
  form_id,
  private_key = NULL,
  start_date = as.POSIXct("2000-01-01"),
  status = c("approved", "rejected", "pending"),
  tidy = TRUE
)

Arguments

form_id	A string specifying the SurveyCTO form ID.
private_key	An optional path to a .pem private key file. Required if the form is encrypted.
start_date	A POSIXct timestamp. Only submissions received after this date/time are requested. Defaults to "2000-01-01".
status	A character vector of submission statuses to include. Must be a subset of "approved", "rejected", and "pending". Defaults to all three.
tidy	Logical; if TRUE, attempts to clean and restructure the raw SurveyCTO output using the XLSForm definition.

Details

When tidy = TRUE, the function performs several common post-processing steps:

• Type conversion: Converts numeric, date, and datetime fields to native R types based on question types in the XLSForm.

• Structural cleanup: Removes layout-only fields such as notes, group markers, and repeat delimiters.

• Column ordering: Places key submission metadata (for example, completion and submission dates) first, followed by survey variables in form order.

• Media fields: Strips URLs from image, audio, and video fields, leaving only the filename.

• Geopoints: Splits geopoint variables into four columns with ⁠_latitude⁠, ⁠_longitude⁠, ⁠_altitude⁠, and ⁠_accuracy⁠ suffixes when not already present.

Value

A data.frame containing the downloaded submissions.

If tidy = FALSE, the raw parsed JSON response is returned. If tidy = TRUE, a cleaned version with standardized column types and ordering is returned.

Returns an empty data.frame when no submissions are available.

See Also

Other Form Management Functions: cto_form_attachment(), cto_form_data_attachment(), cto_form_dofile(), cto_form_languages(), cto_form_metadata()

Examples

## Not run: 
# Download raw submissions
raw <- cto_form_data("my_form_id", tidy = FALSE)

# Download and tidy encrypted data
clean <- cto_form_data("my_form_id", private_key = "keys/my_key.pem")

## End(Not run)

ctoclient documentation built on March 28, 2026, 5:07 p.m.