# A quick introduction to robotoolbox

`robotoolbox` is an R client for retrieving data from `KoboToolbox`.

`robotoolbox` uses `KoboToolbox API v2` with the primary aim of simplifying the process of accessing your collected data.

# Configure robotoolbox

In order to use `robotoolbox`, you need to configure and specify your API token and your `KoboToolbox` server URL. An API token is a unique identifier that acts like a combination of username and password. It allows you to authenticate to the `KoboToolbox` API to access your data. The simplest way to configure `robotoolbox` is to store your API token and server URL in your `.Renviron` file.

We use the environment variables `KOBOTOOLBOX_URL` and `KOBOTOOLBOX_TOKEN` for the URL and the token, respectively. You can use the `usethis` package and the `usethis::edit_r_environ()` function to add these environment variables to your `.Renviron` file.

The following examples will utilize UNHCR `KoboToolbox` server URL (https://kobo.unhcr.org/). You can replace this URL by the one you use, it can be https://kf.kobotoolbox.org/, https://eu.kobotoolbox.org/ or any other `KoboToolbox` server URL you typically use.

    KOBOTOOLBOX_URL="https://kobo.unhcr.org/"
    KOBOTOOLBOX_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxx

In an interactive session, you can directly use the `kobo_setup` function.

    library(robotoolbox)
    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 set the `page_size` parameter or the `KOBOTOOLBOX_PAGE_SIZE` environment variable:

    kobo_setup(url = "https://my-private-server.org",
               token = "xxxxxxxxxxxxxxxxxxxxxxxxxx",
               page_size = 30000)

Or in your `.Renviron`:

    KOBOTOOLBOX_PAGE_SIZE=30000

You can manually retrieve your `token` through the `KoboToolbox` account settings in the web interface. There is also a `kobo_token` function to do the same thing automagically from `R`.

    token <- kobo_token(username = "cool_user_name",
                        password = "gRe@TP@$$WoRd",
                        overwrite = TRUE)

You can then use this token in your `.Renviron` or during the setup using `kobo_setup`.

    kobo_setup(url = "https://kobo.unhcr.org",
               token = token)

You can verify the settings using the `kobo_settings` function.

    kobo_settings()
    ## <robotoolbox settings>
    ##    KoboToolbox URL: https://kobo.unhcr.org/
    ##    KoboToolbox API Token: xxxxxxxxxxxxxxxxxxxxxxxxxx

# KoboToolbox API assets

## List your projects

You can view and list all your `KoboToolbox` projects (also known as `assets`) through the web interface.

With `robotoolbox`, you can achieve a similar outcome in `R` using `kobo_asset_list` function.

    library(robotoolbox)
    library(dplyr)
    asset_list <- kobo_asset_list()

    asset_list |>
      slice_head(n = 6) |>
      knitr::kable()

uid | name | asset_type | owner_username | date_created | date_modified | submissions
--- | --- | --- | --- | --- | --- | ---
anCXJBQttAghX8oFeNvgSW | PCS Survey | survey | dickoa | 2022-02-20 14:51:36 | 2022-02-20 14:51:47 | 1
aEwTYNcU76UvLgiY89rPWm | Pan-African Capacity Building in R | survey | rrc_rrrp19 | 2022-01-06 14:33:35 | 2022-01-28 12:31:28 | 95
aWGgYSXbJn3nnqr2qxTxSB | External file v3 | survey | dickoa | 2022-01-26 11:38:45 | 2022-01-26 11:39:41 | 1
aREsLnfwNU9L7ePbUjnajg | Multiple languages 2 | survey | dickoa | 2022-01-18 20:31:47 | 2022-01-18 20:37:10 | 3
aYuTZn9vegi3Z49MXwKjep | Multiple languages | survey | dickoa | 2022-01-07 10:37:18 | 2022-01-07 10:37:35 | 5
aiNdJzr9RzG8V57exPZbsS |  | empty | dickoa | 2022-01-07 10:36:28 | 2022-01-07 10:36:28 | 0

## KoboToolbox asset

You can also manipulate directly each `asset` (project) using the `kobo_asset` function. On the server, an asset is uniquely identified by a `uid`.

    uid <- "aYuTZn9vegi3Z49MXwKjep"
    asset <- kobo_asset(uid)
    asset

    #> <robotoolbox asset>  aYuTZn9vegi3Z49MXwKjep
    #>   Asset name: Multiple languages
    #>   Asset type: survey
    #>   Asset owner: dickoa
    #>   Created: 2022-01-07 10:37:19
    #>   Last modified: 2023-09-07 07:27:34
    #>   Submissions: 5

As `asset_list` is a `data.frame` containing the list of assets, we can subset it and select the `uid` of interest based on the available metadata.

As an example, you can get the `uid` associated to the asset (survey) named `Multiple languages`.

    asset_list |>
      filter(name == "Multiple languages") |>
      pull(uid)

    #> [1] "aYuTZn9vegi3Z49MXwKjep"

You can then retrieve the associated `asset` object using the `kobo_asset` function.

    asset_list |>
      filter(name == "Multiple languages") |>
      pull(uid) |>
      kobo_asset()

    #> <robotoolbox asset>  aYuTZn9vegi3Z49MXwKjep
    #>   Asset name: Multiple languages
    #>   Asset type: survey
    #>   Asset owner: dickoa
    #>   Created: 2022-01-07 10:37:19
    #>   Last modified: 2023-09-07 07:27:34
    #>   Submissions: 5

A `kobo_asset` provides basic information about your project. You can easily get the name, its type (survey), the number of submissions, when the project was created, and when it was last modified.

# KoboToolbox data

The `kobo_data` function (or its alias `kobo_submissions`) is the main function in `robotoolbox`, and it fetches your data from the server, as its name suggests.

We can illustrate its usage by trying to read data from the same survey named `Multiple languages`.

We can follow the steps mentioned above to get the `uid`, and the `asset`.

    asset_ml <- asset_list |>
      filter(name == "Multiple languages") |>
      pull(uid) |>
      kobo_asset()
    asset_ml

    #> <robotoolbox asset>  aYuTZn9vegi3Z49MXwKjep
    #>   Asset name: Multiple languages
    #>   Asset type: survey
    #>   Asset owner: dickoa
    #>   Created: 2022-01-07 10:37:19
    #>   Last modified: 2023-09-07 07:27:34
    #>   Submissions: 5

Then, we can use the `asset_ml` object, which uniquely identifies the `Multiple languages` asset, to read its data.

    data_ml <- kobo_data(asset_ml)

    data_ml |>
      select(start:uuid) |>
      slice_head(n = 3) |>
      knitr::kable()

start | end | today | full_name | pet_yesno | _id | uuid
--- | --- | --- | --- | --- | --- | ---
2022-01-07 10:39:37 | 2022-01-07 10:39:47 | 2022-01-07 | Jean-Pierre | 0 | 17735002 | 5388c680d19148828ea45913af820f30
2022-01-07 10:39:47 | 2022-01-07 10:40:02 | 2022-01-07 | Fatim | 1 | 17735003 | 5388c680d19148828ea45913af820f30
2022-01-07 10:37:39 | 2022-01-07 10:38:20 | 2022-01-07 | Ahmad | 0 | 17734994 | 5388c680d19148828ea45913af820f30

## Filtering and selecting fields

You can filter submissions server-side using the `query` parameter, which accepts a MongoDB-style query string. This avoids downloading the full dataset when you only need a subset.

    ## Only submissions where pet_yesno is "1" (Yes)
    data_pet <- kobo_data(asset_ml, query = '{"pet_yesno": "1"}')

You can also select specific fields to reduce data transfer using the `fields` parameter.

    ## Fetch only name and pet_yesno columns
    data_partial <- kobo_data(asset_ml, fields = c("full_name", "pet_yesno"))

# KoboToolbox form

`robotoolbox` allows you to display and manipulate `KoboToolbox` survey forms. You can pull the form from a particular survey using the `kobo_form` function.

    asset_ml |>
      kobo_form() |>
      knitr::kable()

name | list_name | type | label | lang | kuid | version | choices
--- | --- | --- | --- | --- | --- | --- | ---
start | NA | start | NA | English (en) | Cypi2O0NQ | vW6fMPTWKJmBfdSRM7jd4V |
end | NA | end | NA | English (en) | F2Erecceg | vW6fMPTWKJmBfdSRM7jd4V |
today | NA | today | NA | English (en) | 6WnNQUnlF | vW6fMPTWKJmBfdSRM7jd4V |
full_name | NA | text | What is your name? | English (en) | pkEk0bzX7 | vW6fMPTWKJmBfdSRM7jd4V |
full_name | NA | text | Quel est votre nom ? | Francais (fr) | pkEk0bzX7 | vW6fMPTWKJmBfdSRM7jd4V |
full_name | NA | text | ما اسمك ؟ | Arabic (ar) | pkEk0bzX7 | vW6fMPTWKJmBfdSRM7jd4V |
pet_yesno | yesno | select_one | Do you have any pet? | English (en) | a1xXud0rG | vW6fMPTWKJmBfdSRM7jd4V | 1 , 1 , 1 , 0 , 0 , 0 , Yes , Oui , نعم , No , Non , لا , English (en) , Francais (fr), Arabic (ar) , English (en) , Francais (fr), Arabic (ar)
pet_yesno | yesno | select_one | Avez-vous un animal de compagnie ? | Francais (fr) | a1xXud0rG | vW6fMPTWKJmBfdSRM7jd4V | 1 , 1 , 1 , 0 , 0 , 0 , Yes , Oui , نعم , No , Non , لا , English (en) , Francais (fr), Arabic (ar) , English (en) , Francais (fr), Arabic (ar)
pet_yesno | yesno | select_one | هل تمتلك حيوانا أليفا ؟ | Arabic (ar) | a1xXud0rG | vW6fMPTWKJmBfdSRM7jd4V | 1 , 1 , 1 , 0 , 0 , 0 , Yes , Oui , نعم , No , Non , لا , English (en) , Francais (fr), Arabic (ar) , English (en) , Francais (fr), Arabic (ar)

Which is a representation in `robotoolbox` of the following form

- Survey questions

type | name | label::English (en) | label::Francais (fr) | label::Arabic (ar)
--- | --- | --- | --- | ---
start | start |  |  |
end | end |  |  |
today | today |  |  |
text | full_name | What is your name? | Quel est votre nom ? | ما اسمك ؟
select_one yesno | pet_yesno | Do you have any pet? | Avez-vous un animal de compagnie ? | هل تمتلك حيوانا أليفا ؟

- Choices

list_name | name | label::English (en) | label::Francais (fr) | label::Arabic (ar)
--- | --- | --- | --- | ---
yesno | 1 | Yes | Oui | نعم
yesno | 0 | No | Non | لا

# Wrapping up

`robotoolbox` is a powerful R client for interfacing with the `KoboToolbox`. Its primary purpose is to simplify and streamline the process of accessing and managing data collected through `KoboToolbox`. With the use of functions like `kobo_setup`, `kobo_asset`, and `kobo_data`, users can effortlessly configure their settings, manipulate their projects (or `assets`), and load their data directly from the server. It also comes with utilities to manipulate audit log data for automatic survey data quality control (`kobo_audit`) or to download media attachments (`kobo_attachment_download`).

Overall, `robotoolbox` serves as an essential tool for researchers and data analysts who rely on `KoboToolbox` for data collection and seek an efficient way to integrate their work with the R environment.