Type: Package
Title: Access your Coletum's Data from API
Version: 1.0.0
Maintainer: André Smaniotto <smaniotto@geosapiens.com.br>
Description: Get your data (forms, structures, answers) from Coletum https://coletum.com to handle and analyse.
License: LGPL-3
URL: https://github.com/geo-sapiens/RColetum
BugReports: https://github.com/geo-sapiens/RColetum/issues
Encoding: UTF-8
Imports: httr, jsonlite, dplyr, stats
RoxygenNote: 7.3.2
Suggests: testthat
NeedsCompilation: no
Packaged: 2026-04-16 21:53:04 UTC; andresmaniotto
Author: André Smaniotto [aut, cre], Marcelo Magnani [aut], Rodrigo Sant'Ana [aut], GeoSapiens [cph, fnd]
Depends: R (≥ 4.1.0)
Repository: CRAN
Date/Publication: 2026-04-16 22:12:04 UTC

RColetum

Description

An R package to get data from Coletum.

RColetum functions

The currents functions that are provide by RColetum are:

Author(s)

Maintainer: André Smaniotto smaniotto@geosapiens.com.br

Authors:

Other contributors:

See Also

Useful links:

Flatten a GetAnswers result into a single data frame.

Description

Converts the output of GetAnswers into a single flat data.frame. Works with any form: if the form is simple (no groups or multivalued fields), GetAnswers already returns a plain data.frame and this function returns it unchanged. For forms with groups or multivalued fields, the main data frame and all nested data frames are joined using dplyr::full_join.

Usage

FlattenAnswers(answers)

Arguments

answers

The return value of GetAnswers: either a plain data.frame (simple form) or a list with a main data frame and nested data frames (form with groups or multivalued fields).

Details

When the form contains multivalued groups or fields, each submission may produce multiple rows in the nested data frames. Joining them to the main data frame causes row duplication: each combination of main row and nested row is represented. Account for this in any aggregation.

Value

A single data.frame. For simple forms the columns keep their original names. For forms with groups, main-frame columns are prefixed with "answer." and nested-frame columns are prefixed with their group componentId.

Examples


answers <- GetAnswers("cizio7xeohwgc8k4g4koo008kkoocwg", 5719)
FlattenAnswers(answers)

# Pipe-friendly
GetAnswers("cizio7xeohwgc8k4g4koo008kkoocwg", 5719) |> FlattenAnswers()

Get all the answers of a form.

Description

Get all the current answers of a specific form. This function calls GetForm internally to understand the form structure.

Usage

GetAnswers(
  token,
  idForm,
  nameForm = NULL,
  source = NULL,
  createdAfter = NULL,
  createdBefore = NULL,
  updatedAfter = NULL,
  updatedBefore = NULL,
  createdBy = NULL,
  updatedBy = NULL,
  page = 1,
  page_size = 100,
  all_pages = TRUE
)

Arguments

token

String access token.

idForm

Numeric Id of the required form.

nameForm

String name of the required form. Used only when idForm is not supplied. When this parameter is used, one extra access quota is spent.

source

Optional filter. Origin of the answer: "web_public", "web_private" or "mobile".

createdAfter

Optional filter. Returns answers created after this date (exclusive). Accepts ISO 8601 format ("YYYY-MM-DD" or "YYYY-MM-DDThh:mm:ssTZD").

createdBefore

Optional filter. Returns answers created before this date (exclusive). Accepts ISO 8601 format.

updatedAfter

Optional filter. Returns answers updated after this date (exclusive). Accepts ISO 8601 format.

updatedBefore

Optional filter. Returns answers updated before this date (exclusive). Accepts ISO 8601 format.

createdBy

Optional filter. Returns answers created by the user with this numeric ID.

updatedBy

Optional filter. Returns answers whose last update was made by the user with this numeric ID.

page

Integer. Starting page when all_pages = FALSE. Default: 1.

page_size

Integer. Number of records per API request (max 500). Default: 100.

all_pages

Logical. If TRUE (default), fetches all pages automatically and returns a combined result. If FALSE, returns only the page specified by page.

Details

To get more details about the fields provided by the result, please visit the API documentation.

Value

A list with two elements when the form has groups or multivalued fields: the first element is the main data frame (scalar fields and metadata), the second is a named list of nested data frames linked by main_df_id. For simple forms with no groups or multivalued fields, a single data.frame is returned directly. Use FlattenAnswers to join everything into one flat table.

Metadata columns in the main data frame: main_df_id, created_by_user_name, created_by_user_id, created_at_source, created_at, created_at_coordinates.latitude, created_at_coordinates.longitude, updated_at, updated_at_coordinates.latitude, updated_at_coordinates.longitude.

Examples


GetAnswers("cizio7xeohwgc8k4g4koo008kkoocwg", 5705)
GetAnswers(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
             nameForm = "RColetum Test - Iris")
GetAnswers(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
             idForm = 5705,
             createdAfter = "2012-12-20",
             createdBefore = "2018-12-20")
GetAnswers(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
             idForm = 5705,
             source = "web_public",
             createdAfter = "2012-12-20T19:20:30+01:00",
             createdBefore = "2018-12-20T19:20:30+01:00")
GetAnswers(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
             idForm = 5705,
             all_pages = FALSE,
             page = 1,
             page_size = 3)

Get form metadata and field structure.

Description

Retrieves the metadata and complete component (field) structure of a specific form. This function replaces the former GetFormStructure.

Usage

GetForm(token, idForm, nameForm = NULL)

Arguments

token

A string access token.

idForm

Numeric Id of the required form.

nameForm

String name of the required form. Used only when idForm is not supplied. When this parameter is used, one extra access quota is spent.

Details

To get more details about the fields provided by the result, please visit the API documentation.

Value

A list with elements: id, name, description, status, category, version, public_answers, and components (a nested data frame representing the form's field schema, where each row is a component with columns id, type, label, help_block, maximum, minimum, visibility, and — for group components — components).

Examples


GetForm("cizio7xeohwgc8k4g4koo008kkoocwg", 5705)
GetForm("cizio7xeohwgc8k4g4koo008kkoocwg", nameForm = "RColetum Test - Iris")
GetForm(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
        nameForm = "RColetum Test - Iris")

Get info of all forms.

Description

Retrieve information about all forms in the account.

Usage

GetForms(
  token,
  status = NULL,
  name = NULL,
  page = 1,
  page_size = 100,
  all_pages = TRUE
)

Arguments

token

String access token.

status

Optional filter. State of the form: "enabled" or "disabled".

name

Optional filter. Returns forms whose name contains this string (partial match, case-insensitive).

page

Integer. Starting page when all_pages = FALSE. Default: 1.

page_size

Integer. Number of records per API request (max 500). Default: 100.

all_pages

Logical. If TRUE (default), fetches all pages automatically and returns a combined data frame. If FALSE, returns only the page specified by page.

Details

To get more details about the fields provided by the result, please visit the API documentation.

Value

A data frame with columns: id, name, description, status, category, version, public_answers. Returns NULL with a warning if no forms are found.

Examples


GetForms("cizio7xeohwgc8k4g4koo008kkoocwg")
GetForms("cizio7xeohwgc8k4g4koo008kkoocwg", status = "enabled")
GetForms("cizio7xeohwgc8k4g4koo008kkoocwg", name = "Iris")
GetForms("cizio7xeohwgc8k4g4koo008kkoocwg", page_size = 3, all_pages = FALSE)