Title: | Client for the 'KoboToolbox' API |
---|---|
Description: | Suite of utilities for accessing and manipulating data from the 'KoboToolbox' API. 'KoboToolbox' is a robust platform designed for field data collection in various disciplines. This package aims to simplify the process of fetching and handling data from the API. Detailed documentation for the 'KoboToolbox' API can be found at <https://support.kobotoolbox.org/api.html>. |
Authors: | Ahmadou Dicko [aut, cre, cph], Hisham Galal [ctb] |
Maintainer: | Ahmadou Dicko <[email protected]> |
License: | MIT + file LICENSE |
Version: | 1.3.8.9005 |
Built: | 2024-11-09 16:24:54 UTC |
Source: | https://github.com/dickoa/robotoolbox |
Examples of KoboToolbox assets and list of assets.
asset_list asset_ml asset_rg asset_spatial asset_sm_label asset_audit
asset_list asset_ml asset_rg asset_spatial asset_sm_label asset_audit
asset_list: a data.frame
of 28 rows and 7 columns with a list of API assets
asset_ml: A kobo_asset
object on a survey using multiple languages.
asset_rg: A kobo_asset
object on a survey using repeat groups.
asset_spatial: A kobo_asset
object on a survey showcasing gps questions.
asset_sm_label: A kobo_asset
object to showcase select multiple labels.
asset_audit: A kobo_asset
object on a survey with audit logging enabled.
Examples of KoboToolbox submissions data.
data_ml_en data_ml_fr data_ml_ar data_ml_default data_ml_vlabel data_rg data_spatial data_sm data_sm_label data_audit
data_ml_en data_ml_fr data_ml_ar data_ml_default data_ml_vlabel data_rg data_spatial data_sm data_sm_label data_audit
data_ml: A data.frame
with submissions from asset_ml
in English.
data_ml_fr: A data.frame
with submissions from asset_ml
in French.
data_ml_ar: A data.frame
with submissions from asset_ml
in Arabic
data_ml_default: A data.frame
with submissions from asset_ml
with the default language.
data_ml_vlabel: A data.frame
with submissions from asset_ml
using variable labels as column names.
data_rg: A dm
object with submissions from asset_rg
data_spatial: A data.frame
with submissions from
the asset_spatial
KoboToolbox API asset.
data_sm: A data.frame
with submissions from
asset_sm_label
with no labels for the select_multiple
question.
data_sm_label: A data.frame
with submissions from
asset_sm_label
with labels for the select_multiple
question.
data_audit: A data.frame
with submissions from asset_audit
.
Get a specific KoboToolbox API asset from a unique identifier
kobo_asset(x)
kobo_asset(x)
x |
the unique identifier of a specific asset ( |
A kobo_asset
object. It contains all the information about the
KoboToolbox API asset associated to the unique identifier.
## Not run: # replace by your own url and token kobo_setup(url = "https://kf.kobotoolbox.org", token = "abcde") # use a valid uid uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) asset ## End(Not run)
## Not run: # replace by your own url and token kobo_setup(url = "https://kf.kobotoolbox.org", token = "abcde") # use a valid uid uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) asset ## End(Not run)
List all uploaded files related to a KoboToolbox API asset
kobo_asset_file_list(x)
kobo_asset_file_list(x)
x |
the asset uid or the |
A data.frame
containing the list of all your KoboToolbox API files under
the asset:
uid
the asset unique identifier
url
url of the files API endpoint
asset
url of the files associated asset API endpoint
user
the user account of the owner of the asset
user__username
when the asset was created
file_type
files type either form_media
or map_layer
description
files description
date_created
date when the files were created
content
url to download the files
hash
md5 hash of the files
filename
names of the files
mimetype
mime type of the files
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzA5hzkjRUWi" kobo_file_list(uid) ## End(Not run)
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzA5hzkjRUWi" kobo_file_list(uid) ## End(Not run)
List all available KoboToolbox API assets and their metadata.
kobo_asset_list(limit = 100L)
kobo_asset_list(limit = 100L)
limit |
integer, the number of API assets to display per page. Default to 100. |
A data.frame
containing the list of all your KoboToolbox API assets
and the following metadata:
uid
the asset unique identifier
name
the name of the asset
asset_type
the type of asset (block
, survey
, question
, or template
)
owner_userame
the user account of the owner of the asset
date_create
when the asset was created
date_modified
when the asset was last modified
deployed
whether or not the asset is currently deployed
submissions
the number of submissions for the asset (survey
)
## Not run: kobo_setup() asset_list <- kobo_asset_list(limit = 10L) asset_list ## End(Not run)
## Not run: kobo_setup() asset_list <- kobo_asset_list(limit = 10L) asset_list ## End(Not run)
Get a specific KoboToolbox Asset version from an asset unique identifier
or kobo_asset
object
kobo_asset_version(x, version)
kobo_asset_version(x, version)
x |
the unique identifier of a specific asset ( |
version |
character, the unique identifier of the version of the asset |
A kobo_asset_version
object
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) asset_version_list <- kobo_asset_version_list(asset) kobo_asset_version(asset, asset_version_list$uid[1]) ## End(Not run)
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) asset_version_list <- kobo_asset_version_list(asset) kobo_asset_version(asset, asset_version_list$uid[1]) ## End(Not run)
List all available versions of a KoboToolbox API asset and their metadata.
kobo_asset_version_list(x)
kobo_asset_version_list(x)
x |
the uid or |
A data.frame
containing the list of all the versions
of a given KoboToolbox API asset with the following metadata:
uid
the asset version unique identifier.
url
the URL of the asset version.
deployed
whether or not the asset version is deployed
date_modified
when the asset version was last modified
a data.frame
## Not run: kobo_setup() # setup using your url and token uid <- "a9cwEQcbWqWzA5hzkjRUWi" # pick a valid uid asset <- kobo_asset(uid) kobo_asset_version_list(asset) ## End(Not run)
## Not run: kobo_setup() # setup using your url and token uid <- "a9cwEQcbWqWzA5hzkjRUWi" # pick a valid uid asset <- kobo_asset(uid) kobo_asset_version_list(asset) ## End(Not run)
Download submitted files associatted to a KoboToolbox API asset
kobo_attachment_download(x, folder, progress, overwrite, n_retry)
kobo_attachment_download(x, folder, progress, overwrite, n_retry)
x |
the asset uid or the |
folder |
character, the folder where you store the downloaded files. The working directory is the default folder. |
progress |
logical, whether or not you want to see the progess via message.
Default to |
overwrite |
logical, whether or not you want to overwrite existing media files.
Default to |
n_retry |
integer, Number of time you should retry the failed request. Default to 3L. |
Silently returns a vector of files paths.
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzA5hzkjRUWi" kobo_attachment_download(uid, folder = tempdir()) ## End(Not run)
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzA5hzkjRUWi" kobo_attachment_download(uid, folder = tempdir()) ## End(Not run)
Get all audit logs data from a KoboToolbox survey through a kobo_asset
or
asset unique identifier.
kobo_audit(x, progress)
kobo_audit(x, progress)
x |
the unique identifier of a specific asset ( |
progress |
logical, whether or not you want to see the progess via message.
Default to |
A data.frame
. It contains survey paradata from audit logs.
The following columns are available:
_id
This columns generated by robotoolbox
allow you to do a mapping
the _id
of the submissions in kobo_data
.
event
the action that took place. The different event types include.
form start, form exit, question, group questions, end screen, and device
or metadata audit.
node
the name of the question or group related to the event.
name
This column is appended by robotoolbox
to match the name of the question
in the audit and the data from kobo_data
.
start
the timestamp when the event started.
end
the timestamp when the event ended.
latitude
the latitude of the device when the event occurred.
longitude
the longitude of the device when the event occurred.
accuracy
the GPS accuracy of the location data.
old-value
the previous value of the question before it was changed in this event.
new-value
the new value of the question after it was changed in this event.
user
the username of the data collector.
change-reason
the reason before they save changes to a form.
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzdA5eqkjRUWi" asset <- kobo_asset(uid) audit <- kobo_audit(asset) if (require(dplyr)) { library(dplyr) glimpse(audit) } ## End(Not run)
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzdA5eqkjRUWi" asset <- kobo_asset(uid) audit <- kobo_audit(asset) if (require(dplyr)) { library(dplyr) glimpse(audit) } ## End(Not run)
Get all submissions from a KoboToolbox API asset through a kobo_asset
or
asset unique identifier.
kobo_data( x, lang, all_versions, colnames_label, select_multiple_label, select_multiple_sep, progress, paginate, page_size ) kobo_submissions( x, lang, all_versions, colnames_label, select_multiple_label, select_multiple_sep, progress, paginate, page_size ) ## S3 method for class 'kobo_asset' kobo_submissions( x, lang = NULL, all_versions = TRUE, colnames_label = FALSE, select_multiple_label = FALSE, select_multiple_sep = "_", progress = FALSE, paginate = NULL, page_size = NULL ) ## S3 method for class 'character' kobo_submissions( x, lang = NULL, all_versions = TRUE, colnames_label = FALSE, select_multiple_label = FALSE, select_multiple_sep = "_", progress = FALSE, paginate = NULL, page_size = NULL ) ## Default S3 method: kobo_submissions( x, lang = NULL, all_versions = TRUE, colnames_label = FALSE, select_multiple_label = FALSE, select_multiple_sep = "_", progress = FALSE, paginate = NULL, page_size = NULL )
kobo_data( x, lang, all_versions, colnames_label, select_multiple_label, select_multiple_sep, progress, paginate, page_size ) kobo_submissions( x, lang, all_versions, colnames_label, select_multiple_label, select_multiple_sep, progress, paginate, page_size ) ## S3 method for class 'kobo_asset' kobo_submissions( x, lang = NULL, all_versions = TRUE, colnames_label = FALSE, select_multiple_label = FALSE, select_multiple_sep = "_", progress = FALSE, paginate = NULL, page_size = NULL ) ## S3 method for class 'character' kobo_submissions( x, lang = NULL, all_versions = TRUE, colnames_label = FALSE, select_multiple_label = FALSE, select_multiple_sep = "_", progress = FALSE, paginate = NULL, page_size = NULL ) ## Default S3 method: kobo_submissions( x, lang = NULL, all_versions = TRUE, colnames_label = FALSE, select_multiple_label = FALSE, select_multiple_sep = "_", progress = FALSE, paginate = NULL, page_size = NULL )
x |
the asset uid or the |
lang |
character, form language used for the variable and value labels. |
all_versions |
logical, whether or not to include submissions from all form versions.
Default to |
colnames_label |
logical, whether or not to use variable labels
in lieu of column names based on form question names. Default to |
select_multiple_label |
logical, whether or not to replace select_multiple columns values by labels. Default to |
select_multiple_sep |
character, column and choices separator for newly created dummy variables. Default to "_". |
progress |
logical, whether or not you want to see the progess via message.
Default to |
paginate |
logical, split submissions by page_size. Default to |
page_size |
integer, number of submissions per page. |
kobo_data
is the main function of robotoolbox
, it is used
pull submissions from your Kobotoolbox survey. The main result is a data.frame
for regular form and you have a dm
for a form with repeating groups of questions.
A data.frame
or A dm
object if you have a repeating
group of questions. It contains the responses from the Kobotoolbox survey.
## Not run: # Use your own URL and token kobo_setup(url = "https://kf.kobotoolbox.org/", token = "9et1814c285w094f6v9bd629df47a1a0e81x53a0") # Use your own unique identifier uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) subs <- kobo_data(asset) if (require(dplyr)) { library(dplyr) glimpse(subs) } ## End(Not run)
## Not run: # Use your own URL and token kobo_setup(url = "https://kf.kobotoolbox.org/", token = "9et1814c285w094f6v9bd629df47a1a0e81x53a0") # Use your own unique identifier uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) subs <- kobo_data(asset) if (require(dplyr)) { library(dplyr) glimpse(subs) } ## End(Not run)
Get a KoboToolbox survey form from a kobo_asset
or an asset unique identifier.
kobo_form(x, version)
kobo_form(x, version)
x |
the unique identifier of a specific asset ( |
version |
character, the unique identifier of the version of the asset. |
A data.frame
with the following columns:
name
the name of the survey questions
list_name
the name of list of code used for values and labels
type
the type of KoboToolbox survey questions
label
the label of the questions
lang
the languages used in the survey
version
the survey version unique identifier
choices
a list column with the choices values and labels
kuid
the unique identifier of the question
qpath
and xpath
the path of the question in JSON/XML
You can also have other columns such as relevant
, calculation
, etc. depending on how
you structure for survey form.
## Not run: # Use your own URL and token kobo_setup(url = "https://kf.kobotoolbox.org/", token = "9et1814c285w094f6v9bd629df47a1a0e81x53a0") # Use your own API asset identifier uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) form <- kobo_form(asset) ## End(Not run)
## Not run: # Use your own URL and token kobo_setup(url = "https://kf.kobotoolbox.org/", token = "9et1814c285w094f6v9bd629df47a1a0e81x53a0") # Use your own API asset identifier uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) form <- kobo_form(asset) ## End(Not run)
Get the languages used in a KoboToolbox survey form from a kobo_asset
or asset unique identifier.
kobo_lang(x)
kobo_lang(x)
x |
the unique identifier of a specific asset ( |
A vector of character
. The languages used in the form, it returns "Labels"
when no language is set.
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) lang <- kobo_lang(asset) lang ## End(Not run)
## Not run: kobo_setup() uid <- "a9cwEQcbWqWzA5hzkjRUWi" asset <- kobo_asset(uid) lang <- kobo_lang(asset) lang ## End(Not run)
Print the KoboToolbox server URL and API token currently in use.
kobo_settings()
kobo_settings()
A list with information about your KoboToolbox server URL and token.
## Not run: kobo_settings() ## End(Not run)
## Not run: kobo_settings() ## End(Not run)
Set the KoboToolbox server URL, API token and return invisibly
a kobo_settings
object.
kobo_setup( url = Sys.getenv("KOBOTOOLBOX_URL", ""), token = Sys.getenv("KOBOTOOLBOX_TOKEN", "") )
kobo_setup( url = Sys.getenv("KOBOTOOLBOX_URL", ""), token = Sys.getenv("KOBOTOOLBOX_TOKEN", "") )
url |
character, the base URL of the KoboToolbox server. |
token |
character, the API token. |
A kobo_settings
object pritting the server URL and the API token.
## Not run: # use your own URL and token kobo_setup(url = "https://kf.kobotoolbox.org/", token = "9et1814c285w094f6v9bd629df47a1a0e81x53a0") kobo_settings() ## End(Not run)
## Not run: # use your own URL and token kobo_setup(url = "https://kf.kobotoolbox.org/", token = "9et1814c285w094f6v9bd629df47a1a0e81x53a0") kobo_settings() ## End(Not run)
Get your KoboToolbox API token from your username and password.
kobo_token(username = NULL, password = NULL, url = NULL, overwrite = FALSE)
kobo_token(username = NULL, password = NULL, url = NULL, overwrite = FALSE)
username |
character, KoboToolbox account username. |
password |
character, KoboToolbox account password. |
url |
character, KoboToolbox server URL. |
overwrite |
logical, if |
A character
, the KoboToolbox API token. It also stores, as a side effect,
the URL and token as the environment variables KOBOTOOLBOX_URL
and
KOBOTOOLBOX_TOKEN
respectively.
## Not run: # use your own KoboToolbox URL, username and password if (require(askpass)) { token <- kobo_setup(username = "cool_user_name", password = askpass::askpass(), url = "https://kf.kobotoolbox.org/") token } ## End(Not run)
## Not run: # use your own KoboToolbox URL, username and password if (require(askpass)) { token <- kobo_setup(username = "cool_user_name", password = askpass::askpass(), url = "https://kf.kobotoolbox.org/") token } ## End(Not run)