robotoolbox is an R client to access and manage data
from KoboToolbox, a powerful
tool for collecting and analyzing data in challenging environments.
The package is available on CRAN, Gitlab (dev) and Github (mirror).
install.packages("robotoolbox")You will need the remotes package
to install it from Gitlab and Github. You can also use the pak package to
install it from Github.
## From Gitlab
remotes::install_gitlab("dickoa/robotoolbox")
## From Github
pak::pkg_install("dickoa/robotoolbox")The robotoolbox package is a client to KoboToolbox API v2.
You will need to set your API token and specify the
KoboToolbox server URL. The easiest way to set up
robotoolbox is to store the token and the URL in your
.Renviron file, which is automatically read by
R on startup.
You can retrieve your API token by following the
instruction in the official API documentation: https://support.kobotoolbox.org/api.html.
You can also get your token directly from R using the
kobo_token function.
The following examples will utilize UNHCR KoboToolbox
server url (https://kobo.unhcr.org/). You can replace this URL with
https://kf.kobotoolbox.org/, https://eu.kobotoolbox.org/ or any other
KoboToolbox server URL you typically use.
kobo_token(username = "xxxxxxxxx",
password = "xxxxxxxxx",
url = "https://kobo.unhcr.org")You can either edit directly the .Renviron file or
access it by calling usethis::edit_r_environ() (assuming
you have the usethis package installed) and entering the
following two lines:
KOBOTOOLBOX_URL="https://kobo.unhcr.org/"
KOBOTOOLBOX_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxOr use directly the kobo_setup function
kobo_setup(url = "https://kobo.unhcr.org",
token = "xxxxxxxxxxxxxxxxxxxxxxxxxx")By default, kobo_setup sets a maximum of 1,000
submissions per API request, matching the limit enforced by public
KoboToolbox servers since KoboToolbox KPI version 2.026.03 (March 2026).
If you use a private server with a higher limit, you can configure it
with the page_size parameter:
kobo_setup(url = "https://my-private-server.org",
token = "xxxxxxxxxxxxxxxxxxxxxxxxxx",
page_size = 30000)You can check the settings using the kobo_settings
function.
library("robotoolbox")
kobo_settings()
## <robotoolbox settings>
## KoboToolbox URL: https://kobo.unhcr.org/
## KoboToolbox API Token: xxxxxxxxxxxxxxxxxxxxxxxxxxWith the settings done, it is possible to list all
assets (e.g surveys, questions, etc) for the account
associated to the token and URL.
library("dplyr")
l <- kobo_asset_list()
l
# A tibble: 24 x 7
uid name asset_type owner_username date_created
<chr> <chr> <chr> <chr> <dttm>
1 b9kgvd… Proj_A1… survey xxxxxxxxxxxxx… 2020-04-27 20:34:23
2 aRFJMp… Proj_A2… survey xxxxxxxxxxxxx… 2020-04-27 21:21:12
3 a6qMG7… Proj_A3… survey xxxxxxxxxxxxx… 2021-05-25 16:59:08
4 azhrVs… Proj_A4… survey xxxxxxxxxxxxx… 2021-05-25 13:59:46
5 aReR58… Proj_A5… survey xxxxxxxxxxxxx… 2021-06-07 09:15:53
6 aWaoqy… Proj_A6… survey xxxxxxxxxxxxx… 2021-05-29 10:46:09
7 aABU3C… Proj_A7… survey xxxxxxxxxxxxx… 2020-11-28 15:00:10
8 aaznyX… Proj_A9… survey xxxxxxxxxxxxx… 2020-11-28 14:28:48
9 aCVr2Q… Proj_A9… survey xxxxxxxxxxxxx… 2021-05-25 13:30:24
10 aPxNao… Proj_A10… survey xxxxxxxxxxxxx… 2020-04-27 11:37:34
# … with 14 more rows, and 3 more variables:
# date_modified <dttm>, submissions <int>
glimpse(l)
$ uid <chr> "b9kgvd7AXQCmo5qyUOBEl", "aRfJMpTSGRLzZ…"
$ name <chr> "Proj_A1", "Proj_A2", "Proj_A3", "Proj_A…"
$ asset_type <chr> "survey", "survey", "survey", "survey", …
$ owner_username <chr> "xxxxxxxxxxxxxx", "xxxxxxxxxxxxxxx", "xx…"
$ date_created <dttm> 2020-04-27 20:34:23, 2020-04-27 21:21:1…
$ date_modified <dttm> 2021-06-17 01:52:57, 2021-06-17 01:52:5…
$ submissions <int> 2951, 2679, 2, 1, 0, 0, 287, 73, 0, 274,…The list of assets is a tibble, you can
filter it to select the form unique identifier uid that
uniquely identify the API asset you want to open. The function
kobo_asset can then be used to get the asset
from the uid.
uid <- l |>
filter(name == "proj_A1") |>
pull(uid) |>
first()
uid
## b9agvd9AXQCmo5qyUOBEl
asset <- kobo_asset(uid)
asset
## <robotoolbox asset> b9agvd9AXQCmo5qyUOBEl
## Asset Name: proj_A1
## Asset Type: survey
## Created: 2021-05-10 07:47:53
## Last modified: 2021-08-16 12:35:50
## Submissions: 941Now with the selected asset, we can extract the
submissions using the kobo_submissions
function. The kobo_data can also be used, it’s an alias of
kobo_submissions.
df <- kobo_submissions(asset) ## or df <- kobo_data(asset)
glimpse(df)
## Rows: 941
## Columns: 17
## $ id <int> …
## $ start <dttm> …
## $ end <dttm> …
## $ today <date> …
## $ deviceid <chr> …
## $ test <chr+lbl> …
## $ round <date> …
## $ effective_date <date> …
## $ collect_type <chr+lbl> …
## $ covid_module <chr+lbl> …
## $ country <chr+lbl> …
## $ interviewer_id <chr> …
## $ respondent_is_major <chr+lbl> …
## $ consent <chr+lbl> …
## $ admin_level_1 <chr+lbl> …
## $ admin_level_2 <chr+lbl> …
## $ admin_level_3 <chr+lbl> …You can also filter submissions server-side using a MongoDB-style
query, or select specific fields to reduce
data transfer:
## Filter submissions server-side
df_filtered <- kobo_data(asset, query = '{"consent": "1"}')
## Fetch only specific fields
df_partial <- kobo_data(asset, fields = c("country", "admin_level_1"))robotoolbox uses the R package labelled
to provide tools to manipulate variable labels and value labels. You can
learn more about this here.
Repeating groups associate multiple records to a single record in the
main table. It’s used to group questions that need to be
answered repeatedly. The package dm is used to model such
relationship and allows you to safely query and join such linked data
for your analysis. Learn more about it here
KoboToolbox provides three types of question to record
spatial data: geopoint for points, geotrace
for lines and geoshape to map close polygons.
robotoolbox associates to each spatial column a WKT
column. It provides a simple way to use it with various GIS software and
R package for spatial data analysis. The sf
package is the standard for spatial vector data handling and
visualization. Learn more about it here
KoboToolbox comes with a feature that records all
activities related to a form submission in a log file. The audit logging
metadata is useful for data quality control, security and workflow
management. The kobo_audit function allow you to read
KoboToolbox audit logs file. Learn more in the following
vignette: Audit
Data
ODKOpenDataKit (ODK) is
an open-source tool for collecting data. Similar to
KoboToolbox, ODK utilizes the XLSForm standard for form creation.
Both tools offer similar features and functionality, and data collected
using KoboToolbox can be collected using ODK Collect
as well.
If you are using ODK in conjunction with R, the
ruODK package is an excellent resource. The ruODK R package
served as the primary inspiration for robotoolbox and
provides similar functionality for interacting with ODK data.