Package 'koboAPI'

Title: Access kobo API via R
Description: koboAPI is a package to access and interact with [KoBoToolbox](https://www.kobotoolbox.org/)-based APIs.
Authors: Elliott Messeiller [aut, cre]
Maintainer: Elliott Messeiller <[email protected]>
License: GPL-3
Version: 1.0.1
Built: 2024-11-27 04:40:12 UTC
Source: https://github.com/ElliottMess/koboAPI

Help Index

Assert that the api is valid

Description

Assert that the api is valid

Usage

assert_api(api)

Arguments

api

(character) api to check

Assert that arguments passed in are length 1 character vectors

Description

Assert that arguments passed in are length 1 character vectors

Usage

assert_strings(...)

Arguments

...

Character vectors to check

Authentication for kobo API

Description

Retrieves token if not provided in 'auth_token', then add a 'Authorization' header via add_headers to the API call.

Usage

authenticate_api(auth_type, auth_key = NULL, api)

Arguments

auth_type

(character) Two types of authentication are possible: - 'client': use the 'auth_key' 'user:password' to authenticate to the kobo API - 'token': uses the 'token' provided in 'auth_key' to authenticate
auth_key

(character) Can either be: - A combination of the kobo and password in format: 'user:password‘ (e.g. ’my_user:my_password') - A kobo API V2 token. See the https://support.kobotoolbox.org/api.html
api

(character) The type of API to be used or URL at which the API can be accessed. Can be either: - 'humanitarian_response': "https:://kobo.humanitarianresponse.info" will be used as the base URL (default) - 'kobotoolbox': "https:://https://kf.kobotoolbox.org" will be used as the base URL - 'custom': custom URL. Must at least start with "https://"

Details

All authentication is based on token.

Value

'Authorization' header call via add_headers

Get URL of api

Description

Get URL of api

Usage

get_api_url(api)

Arguments

api

(character) The type of API to be used or URL at which the API can be accessed. Can be either: - 'humanitarian_response': "https:://kobo.humanitarianresponse.info" will be used as the base URL (default) - 'kobotoolbox': "https:://https://kf.kobotoolbox.org" will be used as the base URL - 'custom': custom URL. Must at least start with "https://"

Value

character vector with the URL of the api

Get a data frame with of assets information for the authenticated account.

Description

The function provides a high-level access to APIs based on kobotoolbox. It parses the base URL for the ´api´ and returns the JSON response in a standard format.

Usage

get_asset_id_df(
  api = c("humanitarian_response", "kobotoolbox"),
  auth_type = c("client", "token"),
  auth_key = NULL
)

Arguments

api

(character) The type of API to be used or URL at which the API can be accessed. Can be either: - 'humanitarian_response': "https:://kobo.humanitarianresponse.info" will be used as the base URL (default) - 'kobotoolbox': "https:://https://kf.kobotoolbox.org" will be used as the base URL - 'custom': custom URL. Must at least start with "https://"
auth_type

(character) Two types of authentication are possible: - 'client': use the 'auth_key' 'user:password' to authenticate to the kobo API - 'token': uses the 'token' provided in 'auth_key' to authenticate
auth_key

(character) Can either be: - A combination of the kobo and password in format: 'user:password‘ (e.g. ’my_user:my_password') - A kobo API V2 token. See the https://support.kobotoolbox.org/api.html

Value

A data frame with asset IDs, names, type, and deployment status.

Get a list of asset IDs for the authenticated account.

Description

The function provides a high-level access to APIs based on kobotoolbox. It parses the base URL for the ´api´ and returns the JSON response in a standard format.

Usage

get_asset_id_list(
  api = c("humanitarian_response", "kobotoolbox"),
  auth_type = c("client", "token"),
  auth_key = NULL
)

Arguments

api

(character) The type of API to be used or URL at which the API can be accessed. Can be either: - 'humanitarian_response': "https:://kobo.humanitarianresponse.info" will be used as the base URL (default) - 'kobotoolbox': "https:://https://kf.kobotoolbox.org" will be used as the base URL - 'custom': custom URL. Must at least start with "https://"
auth_type

(character) Two types of authentication are possible: - 'client': use the 'auth_key' 'user:password' to authenticate to the kobo API - 'token': uses the 'token' provided in 'auth_key' to authenticate
auth_key

(character) Can either be: - A combination of the kobo and password in format: 'user:password‘ (e.g. ’my_user:my_password') - A kobo API V2 token. See the https://support.kobotoolbox.org/api.html

Value

A named list of asset IDs

Download data of an asset

Description

Download responses from the API for a specific asset

Usage

get_data(
  asset_id,
  api = api,
  auth_type = c("client", "token"),
  auth_key = NULL
)

Arguments

asset_id

(character) The ID of the form to be accessed (as a character string). Must be a KPI-type ID (not api V1 ID). See download_forms_all for more details.
api

(character) The type of API to be used or URL at which the API can be accessed. Can be either: - 'humanitarian_response': "https:://kobo.humanitarianresponse.info" will be used as the base URL (default) - 'kobotoolbox': "https:://https://kf.kobotoolbox.org" will be used as the base URL - 'custom': custom URL. Must at least start with "https://"
auth_type

(character) Two types of authentication are possible: - 'client': use the 'auth_key' 'user:password' to authenticate to the kobo API - 'token': uses the 'token' provided in 'auth_key' to authenticate
auth_key

(character) Can either be: - A combination of the kobo and password in format: 'user:password‘ (e.g. ’my_user:my_password') - A kobo API V2 token. See the https://support.kobotoolbox.org/api.html

Value

A data frame with the responses data for ´asset_id´

Download form for a specific asset ID

Description

Download form for a specific asset ID

Usage

get_form(
  asset_id,
  api = c("humanitarian_response", "kobotoolbox"),
  auth_type = c("client", "token"),
  auth_key = NULL
)

Arguments

asset_id

(character) The ID of the form to be accessed (as a character string). Must be a KPI-type ID (not api V1 ID). See download_forms_all for more details.
api

(character) The type of API to be used or URL at which the API can be accessed. Can be either: - 'humanitarian_response': "https:://kobo.humanitarianresponse.info" will be used as the base URL (default) - 'kobotoolbox': "https:://https://kf.kobotoolbox.org" will be used as the base URL - 'custom': custom URL. Must at least start with "https://"
auth_type

(character) Two types of authentication are possible: - 'client': use the 'auth_key' 'user:password' to authenticate to the kobo API - 'token': uses the 'token' provided in 'auth_key' to authenticate
auth_key

(character) Can either be: - A combination of the kobo and password in format: 'user:password‘ (e.g. ’my_user:my_password') - A kobo API V2 token. See the https://support.kobotoolbox.org/api.html

Value

A list of three data frames that correspond to the structure of a XLSform: - "survey": a data frame with all the questions variables. - "choices" a data frame with all the choices variables. - "settings" a data frame with the basic settings for the form.

Access to kobo-style APIs

Description

The function provides a high-level access to APIs based on kobotoolbox. It parses the base URL for the ´api´ and returns the JSON response in a standard format.

Usage

kobo_api(
  path,
  api = c("humanitarian_response", "kobotoolbox"),
  auth_type = c("client", "token"),
  auth_key = NULL
)

Arguments

path

(character) additional path to based to the base API URL. It should start with a '/'.
api

(character) The type of API to be used or URL at which the API can be accessed. Can be either: - 'humanitarian_response': "https:://kobo.humanitarianresponse.info" will be used as the base URL (default) - 'kobotoolbox': "https:://https://kf.kobotoolbox.org" will be used as the base URL - 'custom': custom URL. Must at least start with "https://"
auth_type

(character) Two types of authentication are possible: - 'client': use the 'auth_key' 'user:password' to authenticate to the kobo API - 'token': uses the 'token' provided in 'auth_key' to authenticate
auth_key

(character) Can either be: - A combination of the kobo and password in format: 'user:password‘ (e.g. ’my_user:my_password') - A kobo API V2 token. See the https://support.kobotoolbox.org/api.html

Value

a 'kobo_api' object consisting of a list of: - 'content': parsed content from the request - 'path': - 'response': JSON response to request