Package 'KoboconnectR'

Title: Download Data from Kobotoolbox to R
Description: Wrapper for 'Kobotoolbox' APIs ver 2 mentioned at <https://support.kobotoolbox.org/api.html>, to download data from 'Kobotoolbox' to R. Small and simple package that adds immense convenience for the data professionals using 'Kobotoolbox'.
Authors: Asitav Sen [aut, cre, cph]
Maintainer: Asitav Sen <[email protected]>
License: GPL (>= 3)
Version: 2.0.0
Built: 2025-02-27 05:02:22 UTC
Source: https://github.com/asitav-sen/koboconnectr

Help Index

Know your API token or check

Description

'get_kobo_token' is a wrapper for kobotoolbox API 'https://"[url]"/token/?format=json'

Usage

get_kobo_token(
  url = "eu.kobotoolbox.org",
  uname = "",
  pwd = "",
  encoding = "UTF-8"
)

Arguments

url

The '[url]' of kobotoolbox. Default is "eu.kobotoolbox.org".
uname

is username of your kobotoolbox account
pwd

is the password of the account
encoding

is the encoding to be used. Default is "UTF-8".

Details

The function returns the API token.

Value

The function returns the token associated with your id and password in the given url.

Creates a data frame after creating a 'csv' export and downloading it

Description

'kobo_df_download' is a wrapper for kobotoolbox API

Usage

kobo_df_download(
  url = "eu.kobotoolbox.org",
  uname = "",
  pwd = "",
  assetid = "",
  all = "false",
  lang = "_default",
  hierarchy = "false",
  include_grp = "true",
  grp_sep = "/",
  fsep = ";",
  multi_sel = "both",
  media_url = "true",
  fields = NULL,
  sub_ids = NULL,
  sleep = 2
)

Arguments

url

The '[url]' of kobotoolbox Default is "eu.kobotoolbox.org".
uname

is username of your kobotoolbox account
pwd

is the password of the account
assetid

is the id of the asset for which the export is to be created
all

takes logical value in string format. Used to specify whether fields from all form versions will be included in the export.Acceptable values are "true" or "false". Default value is "false".
lang

takes the language. For e.g. "English (en)". For "XML Values as headers", use '_xml'.
hierarchy

takes logical value in string format. Used to specify whether the group hierarchy will be displayed in labels. Acceptable values are "true" or "false". Default value is "false".
include_grp

defines whether or not to include groups. Default value is "true".
grp_sep

is the group separator. Default value is "/".
fsep

is the separator of the downloaded csv file. In most of the cases, it is ";", which is the default. However, if you notice that the separator is the downloaded data is "," or something else, you can change it.
multi_sel

is used to specify the display of multiple_select-type responses. Valid inputs include "both", "summary" or "details". Default is "both".
media_url

This will include an additional column for media-type questions ("question_name_URL") with the URL link to the hosted file. Valid inputs are "true" or "false". Default value is true.
fields

is an array of column names to be included in the export (including their group hierarchy). Valid inputs include: An array containing any string value that matches the XML column name, An empty array which will result in all columns being included, If "fields" is not included in the "export_settings", all columns will be included in the export
sub_ids

is an array of submission ids that will filter exported submissions to only the specified array of ids. Valid inputs include an array containing integer values or an empty array.
sleep

is the sleep time between API actions. For example, it takes time to download an export. But R does not wait for the download to finish before going to next step. Hence the need to provide a break between consecutive API actions. Default value is 2 (seconds).

Details

The function creates an export of survey data in 'csv'. If successful, it attempts to download the data and and return a data frame. Finally, the function attempts to delete the export.

Value

The function returns a data frame of data downloaded from 'Kobotoolbox'.

Create an export

Description

'kobo_export_create' is a wrapper for kobotoolbox API 'https://[kpi-URL]/api/v2/assets/[asset-uid]/exports/'

Usage

kobo_export_create(
  url = "eu.kobotoolbox.org",
  uname = "",
  pwd = "",
  assetid = "",
  type = "csv",
  all = "false",
  lang = "_default",
  hierarchy = "false",
  include_grp = "true",
  grp_sep = "/",
  multi_sel = "both",
  fields = NULL,
  media_url = "true",
  sub_ids = NULL,
  qry = NULL,
  flatten = "true",
  sleep = 3
)

Arguments

url

The '[url]' of kobotoolbox Default is "eu.kobotoolbox.org".
uname

is username of your kobotoolbox account
pwd

is the password of the account
assetid

is the id of the asset for which the export is to be created
type

specifies the export format. Valid formats include "csv","xls", "spss_labels" and "geojson"
all

takes logical value in string format. Used to specify whether fields from all form versions will be included in the export.Acceptable values are "true" or "false". Default value is "false".
lang

takes the language. For e.g. "English (en)". For "XML Values as headers", use '_xml'.
hierarchy

takes logical value in string format. Used to specify whether the group hierarchy will be displayed in labels. Acceptable values are "true" or "false". Default value is "false".
include_grp

defines whether or not to include groups. Default value is "true".
grp_sep

is the group separator. Default value is "/".
multi_sel

is used to specify the display of multiple_select-type responses. Valid inputs include "both", "summary" or "details". Default is "both".
fields

is an array of column names to be included in the export (including their group hierarchy). Valid inputs include: An array containing any string value that matches the XML column name, An empty array which will result in all columns being included, If "fields" is not included in the "export_settings", all columns will be included in the export
media_url

This will include an additional column for media-type questions ("question_name_URL") with the URL link to the hosted file. Valid inputs are "true" or "false". Default value is true.
sub_ids

is an array of submission ids that will filter exported submissions to only the specified array of ids. Valid inputs include an array containing integer values or an empty array.#'
qry

is a JSON object containing a Mongo filter query for filtering exported submissions. Valid inputs include a JSON object containing a valid Mongo query or An empty JSON object (no filtering)
flatten

is a is a boolean (in form of string) value and only relevant when exporting to "geojson" format. Valid inputs are "true" and "false"
sleep

is the sleep time between API actions. For example, it takes time to download an export. But R does not wait for the download to finish before going to next step. Hence the need to provide a break between consecutive API actions. Default value is 2 (seconds).

Details

The function creates an export of survey data. If successful, returns the URL of the data that can be directly downloaded/read/imported in R.

Value

The function creates an export, prints and returns the URL of the export created

See list of exports created

Description

'kobo_exports' is a wrapper for kobotoolbox API 'https://[kpi-url]/api/v2/assets/[assetid]/exports/'

Usage

kobo_exports(
  url = "eu.kobotoolbox.org",
  uname = "",
  pwd = "",
  encoding = "UTF-8",
  assetid = "",
  simplified = FALSE
)

Arguments

url

The '[url]' of kobotoolbox. Default is "eu.kobotoolbox.org".
uname

is username of your kobotoolbox account
pwd

is the password of the account
encoding

is the encoding to be used. Default is "UTF-8"
assetid

the asset id
simplified

if TRUE, then return a simple data frame with selected data, if FALSE returns the full list.

Details

The function returns the export views.

Value

The function returns a list of exports available for the account id and password entered.

Downloads media data from Kobotoolbox

Description

'kobo_media_downloader' downloads media from data downloaded using 'kobo_df_download'. Loops through media columns and downloads files individually.

Usage

kobo_media_downloader(
  url = "eu.kobotoolbox.org",
  uname,
  pwd,
  assetid,
  fsep = ";",
  sleep = 2,
  identifier = "URL",
  timeoutval = 300,
  destfolder = "media"
)

Arguments

url

The '[url]' of kobotoolbox Default is "eu.kobotoolbox.org".
uname

is username of your kobotoolbox account
pwd

is the password of the account
assetid

is the id of the asset for which the export is to be created
fsep

is the separator of the downloaded csv file. In most of the cases, it is ";", which is the default. However,
sleep

is the sleep time between API actions. For example, it takes time to download an export. But R does not wait for the download to finish before going to next step. Hence the need to provide a break between consecutive API actions. Default value is 2 (seconds).
identifier

is the key using with the columns with URL is identified. Default value is "URL" because in most of the cases, the columns containing the URL values end with "URL". Please note that any other column name with similar value may cause error.
timeoutval

is the timeout value in seconds to download the media files. Default is 300 seconds.
destfolder

is the folder where the media is to be stored.

Details

The function creates an export of survey data in 'csv'. If successful, it attempts to download the data and and returns a data frame. From that data frame, the function extracts the URLs of media and attempts to download them.

Value

The function returns a data frame of data downloaded from 'Kobotoolbox'.

Downloads data (xls type) from Kobotoolbox

Description

'kobo_xls_dl' is a wrapper for kobotoolbox API that attemps to download data in excel compatible formal.

Usage

kobo_xls_dl(
  url = "eu.kobotoolbox.org",
  uname = "",
  pwd = "",
  assetid = "",
  all = "false",
  lang = "_default",
  hierarchy = "false",
  include_grp = "true",
  grp_sep = "/",
  multi_sel = "both",
  media_url = "true",
  fields = NULL,
  sub_ids = NULL,
  sleep = 2
)

Arguments

url

The '[url]' of kobotoolbox Default is "eu.kobotoolbox.org".
uname

is username of your kobotoolbox account
pwd

is the password of the account
assetid

is the id of the asset for which the export is to be created
all

takes logical value in string format. Used to specify whether fields from all form versions will be included in the export.Acceptable values are "true" or "false". Default value is "false".
lang

takes the language. For e.g. "English (en)". For "XML Values as headers", use '_xml'.
hierarchy

takes logical value in string format. Used to specify whether the group hierarchy will be displayed in labels. Acceptable values are "true" or "false". Default value is "false".
include_grp

defines whether or not to include groups. Default value is "true".
grp_sep

is the group separator. Default value is "/".
multi_sel

is used to specify the display of multiple_select-type responses. Valid inputs include "both", "summary" or "details". Default is "both".
media_url

This will include an additional column for media-type questions ("question_name_URL") with the URL link to the hosted file. Valid inputs are "true" or "false". Default value is true.
fields

is an array of column names to be included in the export (including their group hierarchy). Valid inputs include: An array containing any string value that matches the XML column name, An empty array which will result in all columns being included, If "fields" is not included in the "export_settings", all columns will be included in the export
sub_ids

is an array of submission ids that will filter exported submissions to only the specified array of ids. Valid inputs include an array containing integer values or an empty array.
sleep

is the sleep time between API actions. For example, it takes time to download an export. But R does not wait for the download to finish before going to next step. Hence the need to provide a break between consecutive API actions. Default value is 2 (seconds).

Details

The function creates an export of survey data in 'xls'. If successful, it attempts to download the data and and return a data frame (reading using 'readxl::read_excel').

Value

The function returns a data frame of data downloaded from 'Kobotoolbox'.

Check kobotoolbox API and retrieve overall info about the projects/assets

Description

'kobotools_api' is a wrapper for kobotoolbox API 'https://[kpi-url]/api/v2/assets/'

Usage

kobotools_api(
  url = "eu.kobotoolbox.org",
  simplified = TRUE,
  uname = "",
  pwd = "",
  encoding = "UTF-8",
  qry = ""
)

Arguments

url

The '[kpi-url]' of kobotoolbox. Default is "eu.kobotoolbox.org"
simplified

A logical value, default is true
uname

takes the username
pwd

takes the password
encoding

is the encoding to be used. Default is "UTF-8".
qry

to add queries

Details

The function takes two variables. First one is 'url' which is the '[kpi-url]'. For most users it will be "eu.kobotoolbox.org" or "kf.kobotoolbox.org". Former is the default. The second parameter is 'simplified' which takes a logical value. If set to true, the function will return selected values from the parsed data and return a data frame. When set to false, a json will be returned with all the details.

Value

The function returns the asset details from the API, inform of a data frame or json.

Extract data from kobotoolbox

Description

'kobotools_kpi_data' is a wrapper for kobotoolbox API 'https://[URL]/api/v2/assets/[assetid]/data/'

Usage

kobotools_kpi_data(
  assetid,
  url = "eu.kobotoolbox.org",
  uname = "",
  pwd = "",
  encoding = "UTF-8",
  format = "json"
)

Arguments

assetid

is the asset id of the asset for which the data is to be downloaded. The id can be found by running [kobotools_data_list_kc()]
url

The '[kpi-url]' of kobotoolbox. Default is "eu.kobotoolbox.org"
uname

is username of your kobotoolbox account
pwd

is the password of the account
encoding

is the encoding to be used. Default is "UTF-8".
format

lets you define the format of output for e.g. json or xml

Details

The function takes the url as one of the inputs. And asset id as another. Both are strings. The asset id is found by running the [kobotools_api()] function.Other parameters are username and password.

Value

The function returns the data in json format