Skip to contents

Usage

Source: vignettes/Usage.Rmd
Usage.Rmd
library(KoboconnectR)
#> Extract Kobotools data to R

Check if you have API token from Kobotoolbox 

library(KoboconnectR)
get_kobo_token(url = "eu.kobotoolbox.org", uname = "userid", pwd = "password")

The output is usually like this

No encoding supplied: defaulting to UTF-8. $token [1] "nask976bdshuiqw9829nsh718"

Extracting data

Extracting data is two step process. Step one is to identify the asset id. And next is to use the asset id to extract the data.

Check the assets you have access to 

kobotools_api(url = "eu.kobotoolbox.org", simplified = T, uname = "userid", pwd = "password")

The output will be a simplified data frame if simplified =T is used in the kobotools_api function.

From the data frame, you can find the asset id you need ((under the column asset)).

Extract the data

Use the asset id and plug in to the kobotools_kpi_data function to download the data.

kobotools_kpi_data(assetid = "assetid", url = "eu.kobotoolbox.org", uname = "username", pwd = "password")

This returns a list from json file. Main data is usually inside results.

Following shows the summary of the list downloaded from one kobotools_kpi_data query.

Downloading: 8.4 kB Length Class Mode count 1 -none- numeric next 0 -none- NULL previous 0 -none- NULL results 39 -none- list

Exports (To download xls and csv)

‘Kobotoolbox’ provides ability to create export of survey results. These exports can be of different formats including ‘csv’ and ‘xls’. The manual process is mentioned the documentation.

Viewing the list of existing exports

Using ‘kobo_exports()’ function, you can view the list of existing exports. This includes URL to the ‘xls’ or ‘csv’ file that you can use to download, import or read files in R.

kobo_exports(url = "eu.kobotoolbox.org", uname = "", pwd = "")

Creating export

Exported data is not updated automatically when new data is entered in the survey. So, you may need to create new export to accommodate new data. To create export, use ‘kobo_export_create()’ function. Please note that ‘Kobotoolbox’ has a limited memory and you may have to delete existing exports manually to clean up.

kobo_export_create(
  url = "eu.kobotoolbox.org", uname = "", pwd = "",
  assetid = "", type = "csv", all = "false", lang = "_default",
  hierarchy = "false", include_grp = "true", grp_sep = "/"
)

On successful execution, the URL of the created export will be returned and printed. You can use this URL to download, import or read data in R.

Find dummy example of how to create export and download csv from Kobotoolbox to R here

Downloading csv file directly

This is a new function which

  1. Creates an export as csv
  2. Downloads the export (And returns)
  3. Deletes the exports after download
kobo_df_download(
  uname = "username", pwd = "password", assetid = "asset",
  lang = "English (en)"
)

Downloading xls file directly

Works on the same principle as that in kobo_df_download, except the exported file is in excel format.

kobo_xls_dl(
  uname = "username", pwd = "password", assetid = "asset",
  lang = "English (en)"
)

Downloading Media Files

This function downloads the file using kobo_df_download then finds the columns with media links and then downloads the files in a loop. This process is time consuming and you may face errors due to timeouts and server load issues.

kobo_media_downloader(uname = "uid", pwd = "password", assetid = "assetid")

In case do not want to use this function, use the data downloaded using kobo_df_download and find the columns where media links exist. Then loop over the values in the column (download using the function download.file()).

Issues and Suggestions

Please feel free to add issue of suggestions in github