Type:	Package
Title:	Connect to the 'nettskjema.no' API of the University of Oslo
Version:	1.0.2
Description:	Enables users to retrieve data, meta-data, and codebooks from https://nettskjema.no/. The data from the API is richer than from the online data portal. Mowinckel (2021) <doi:10.5281/zenodo.4745481>.
License:	MIT + file LICENSE
URL:	https://github.com/CAPRO-UiO/nettskjemar, https://zenodo.org/badge/latestdoi/206264675, https://github.com/capro-uio/nettskjemar
BugReports:	https://github.com/capro-uio/nettskjemar/issues
Depends:	R (≥ 4.1.0)
Imports:	cli, httr2, jsonlite, tools
Suggests:	covr, fs, haven, knitr, labelled, openssl, rmarkdown, spelling, testthat (≥ 2.1.0), vcr (≥ 0.6.0), withr
VignetteBuilder:	knitr
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-06-06 14:09:46 UTC; athanasm
Author:	Athanasia Mo Mowinckel [aut, cre], Trym Nohr Fjørtoft [ctb]
Maintainer:	Athanasia Mo Mowinckel <a.m.mowinckel@psykologi.uio.no>
Repository:	CRAN
Date/Publication:	2025-06-06 14:30:02 UTC

nettskjemar: Connect to the 'nettskjema.no' API of the University of Oslo

Description

Enables users to retrieve data, meta-data, and codebooks from https://nettskjema.no/. The data from the API is richer than from the online data portal. Mowinckel (2021) doi:10.5281/zenodo.4745481.

Author(s)

Maintainer: Athanasia Mo Mowinckel a.m.mowinckel@psykologi.uio.no (ORCID)

Other contributors:

• Trym Nohr Fjørtoft t.n.fjortoft@arena.uio.no (ORCID) [contributor]

See Also

Useful links:

• https://github.com/CAPRO-UiO/nettskjemar

• https://zenodo.org/badge/latestdoi/206264675

• https://github.com/capro-uio/nettskjemar

• Report bugs at https://github.com/capro-uio/nettskjemar/issues

Constructor for nettskjema codebook

Description

Function works on meta-data downloaded from a form. It will return a data.frame in long format with meta-data information from a specific nettskjema form.

Usage

codebook(meta)

Arguments

Value

long format tibble with meta-data for a specific nettskjema

Examples

## Not run: 
meta_110000 <- ns_get_meta(110000)
codebook(meta_110000)

## End(Not run)

Get the raw codebook

Description

The raw codebook is a list of answers and questions with unique ids for both, and the text associated with them. This information can be retrieved from the raw nettskjema data. This can be useful if the nettskjema submission data has been returned with asis = TRUE.

Usage

get_raw_codebook(form_id)

Arguments

Value

long format tibble with meta-data for a specific nettskjema

Examples

## Not run: 
form_id <- 100000
get_raw_codebook(form_id)

Or if the token is saved in a non-standard name
get_raw_codebook(form_id)

## End(Not run)

Check if form has codebook

Description

Codebook is by default turned off in Nettskjema, but best practices in handling data is to have it on. This function checks if the codebook of a form has been activated or not

Usage

has_codebook(form_id)

Arguments

Value

logical is codebook is turned on

Examples

## Not run: 
has_codebook(110000)

## End(Not run)

Add Labels to Dataset

Description

The 'ns_add_labels' function applies labels to variables in a dataset based on a provided codebook. It assigns variable labels, value labels, and metadata required for the "ns-data" class.

Usage

ns_add_labels(data, codebook)

Arguments

Value

A data frame with the same structure as 'data', but with variable and value labels applied. The resulting object is assigned the class '"ns-data"'.

Examples

## Not run: 
data <- ns_get_data(11000)
cb <- ns_get_codebook(11000)
labeled_data <- ns_add_labels(data, cb)

## End(Not run)

Alter checkbox matrix variables in a dataset

Description

This function processes checkbox matrix variables in a dataset, transforming their representations into one of the specified formats.

Usage

ns_alter_checkbox(data, to = c("character", "list"), sep = ",", cb = NULL)

Arguments

Value

A modified 'data.frame' with processed checkbox matrix variables.

Examples

## Not run: 
dt <- ns_get_data(11000)
ns_alter_checkbox(data = dt, to = "list")
ns_alter_checkbox(data = dt, to = "character", sep = ";")

## End(Not run)

Access Nettskjema API Documentation

Description

Opens the browser to display the API documentation for the Nettskjema PI.

Usage

ns_api_docs()

Value

None. Opens a browser window.

Examples

## Not run: 
ns_api_docs()

## End(Not run)

Create an OAuth2 Client for Nettskjema API

Description

This function initializes an OAuth2 client using the 'httr2::oauth_client' function. It is used to authenticate and interact with the Nettskjema API.

Usage

ns_client(client_id, client_secret, client_name = "nettskjemar")

Arguments

Value

A configured 'httr2::oauth_client' object.

Examples

# Example: Initialize an OAuth2 client for Nettskjema
client <- ns_client(
  client_id = "your_client_id",
  client_secret = "your_client_secret"
)

# Using a custom client name
client <- ns_client(
  client_id = "your_client_id",
  client_secret = "your_client_secret",
  client_name = "custom_client_name"
)

Create a Nettskjema Client

Description

Opens the Nettskjema client creation URL in the default web browser.

Usage

ns_create_client()

Details

Use this function to create a new client for accessing Nettskjema APIs.

Value

NULL. Opens the client creation page in a browser.

Examples

## Not run: 
ns_create_client()

## End(Not run)

Save Nettskjema attachments to file

Description

The Nettskjema forms has an option to upload attachments with forms. These can be retrieved by this function. Recommended workflow is to first call ns_list_submission_attachments, and use the output of this to pass along to the function. This function is called by ns_get_form_attachments, but you can use it to define your own output file names.

Usage

ns_get_attachment(attachment_id, path = NULL)

Arguments

Value

httr2-response. saves attachment to file.

Examples

## Not run: 
#submission_id <- c(22222, 1232, 21555)
#attach_dt <- ns_list_submission_attachments(submission_id)
#ns_save_attachment(path = attach_dt$path, output = attach_dt$standardized)

## End(Not run)

Get codebook for a form

Description

With the given API token, will retrieve a list of all the forms you have access to

Usage

ns_get_codebook(form_id, asis = FALSE)

Arguments

Value

list of class ns_meta_data

Examples

## Not run: 
codebook_110000 <- ns_get_codebook(110000)

## End(Not run)

Get data from a form

Description

This function connects to a specific form and fetches all answers. The responses are placed in a data.frame for easy use.

Usage

ns_get_data(form_id, type = NULL)

ns_get_submissions(form_id, type = NULL)

Arguments

Details

"original"

- Returns data in the same tabular format as delivered by Nettskjema.

"long"

- Returns the data in tall format, where there are multiple rows per participant (one per question) and each choice is timestamped.

Value

data.frame

Functions

• ns_get_submissions(): Alternative function name, does the same.

Examples

## Not run: 

# Retrieve all data
data_110000 <- ns_get_data(110000)


## End(Not run)

Retrieve all attachments associated with a Nettskjema

Description

Some Nettskjema have fields for attachments. These can be downloaded through this function. There are two naming convention that may be used for the saved files' names. See output of ns_list_submission_attachments for idea of the names used.

Usage

ns_get_form_attachments(
  form_id,
  filenames = c("standardized", "original"),
  output_dir = "."
)

Arguments

Details

filenames types

"original"

- uses file names are they were uploaded to Nettskjema

"standardized"

- creates file names based on the submission id and a counter number to uniquely create file names for each submission (in case there are more than one attachment)

Value

invisible named logical if the file was saved successfully

Examples

## Not run: 
form_id <- 1100000
ns_get_form_attachments(form_id)

# save files to specific folder
ns_get_form_attachments(form_id, output_dir = "~/Desktop")

# save using original file names
ns_get_form_attachments(form_id, filenames = "original")


## End(Not run)

Download files associated with a form

Description

Each Nettskjema form has several auxiliary forms that can be retrieved.

Usage

ns_get_form_reports(
  form_id,
  type = c("csv", "excel", "spss"),
  path = report_path(form_id, type)
)

Arguments

Value

httr2-response

Examples

## Not run: 
ns_get_form_reports(10009, type="csv")
ns_get_form_reports(10009, type="excel")
ns_get_form_reports(10009, type="spss")
ns_get_form_reports(
  10009,
  type="spss",
  path = "~/Desktop/10009/form.sav"
)

## End(Not run)

Get all forms you have access to

Description

All users have access to specific forms, and this function uses the token provided to check what the current user has access to.

Usage

ns_get_forms(asis = FALSE)

Arguments

Value

data.frame, if asis = TRUE returns a list

Information about the current user

Description

Based on login credential, returns information on the user accessing the Nettskjema PI

Usage

ns_get_me()

Value

list of information

Examples

## Not run: 
ns_get_me()

## End(Not run)

Get metadata for a form

Description

With the given API token, will retrieve the meta-data connected to a form.

Usage

ns_get_meta(form_id)

Arguments

Value

list of class ns_meta_data

Examples

## Not run: 
meta_110000 <- ns_get_meta(110000)


## End(Not run)

Get an individual submission answer

Description

Get an individual submission answer

Usage

ns_get_submission(submission_id)

Arguments

Value

list of all answers

Examples

## Not run: 
ns_get_submission(1100)

## End(Not run)

Get Nettskjema attachments for a submission

Description

Each unique submission ID in Nettskjema may have some attachments. This function saves all attachments associated with a submission ID.

Usage

ns_get_submission_attachments(
  submission_id,
  filenames = "standardized",
  output_dir = paste0("./", submission_id)
)

Arguments

Value

a data.frame with information on attachments available, files written to path

Examples

## Not run: 
submission_id <- 22222
ns_get_submission_attachments(submission_id)
ns_get_submission_attachments(submission_id, "original")


## End(Not run)

Check Environment Variables for Nettskjema Authentication

Description

This function verifies whether the required system variables ('NETTSKJEMA_CLIENT_ID' and 'NETTSKJEMA_CLIENT_SECRET') are set to enable authentication with the Nettskjema API. It provides feedback on the setup status and returns whether the system is correctly configured.

Usage

ns_has_auth(
  client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"),
  client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET")
)

Arguments

Value

Logical. Returns 'TRUE' if both environment variables are set, otherwise 'FALSE'.

References

For more information about authentication setup, see: https://www.capro.dev/nettskjemar/articles/authentication.html

Examples

ns_has_auth()

Retrieve all attachments associated with a Nettskjema

Description

Some Nettskjema have fields for attachments. These can be downloaded through this function. There are two naming convention that may be used for the saved files' names. See output of ns_list_submission_attachments for idea of the names used.

Usage

ns_list_form_attachments(form_id)

Arguments

Details

filenames types

"original"

- uses file names are they were uploaded to Nettskjema

"standardized"

- creates file names based on the submission id and a counter number to uniquely create file names for each submission (in case there are more than one attachment)

Value

invisible named logical if the file was saved successfully

Examples

## Not run: 
form_id <- 1100000
ns_list_form_attachments(form_id)


## End(Not run)

List Nettskjema attachments for a submission

Description

Each unique submission ID in Nettskjema may have some attachments. These can be listed using this function, which will provide the information on where in the Nettskjema API the files are located, their original file names, and a suggested standardized file names for tidier data output.

Usage

ns_list_submission_attachments(submission_id)

Arguments

Value

a data.frame with information on attachments available.

Examples

## Not run: 
submission_id <- 22222
ns_list_submission_attachments(submission_id)


## End(Not run)

Basic Nettskjema httr2 request

Description

Sets the API url and access token. This is used for almost all the functionality in this package. If you want to use endpoints not yet covered by functions in the package, this is the basis function you can build from.

Usage

ns_req(...)

Arguments

Value

httr2 request

Examples

## Not run: 
ns_req() |>
 httr2::req_url_path_append("me") |>
 httr2::req_perform() |>
 httr2::resp_body_json()

## End(Not run)

Authenticate Nettskjema request

Description

After creating a client in Nettskjema, this function will retrieve the access token needed for the remaining processes in the package. Automatically caches the token for more efficient API usage.

Usage

ns_req_auth(
  req,
  client_id = Sys.getenv("NETTSKJEMA_CLIENT_ID"),
  client_secret = Sys.getenv("NETTSKJEMA_CLIENT_SECRET"),
  client_name = "nettskjemar"
)

Arguments

Write codebook to file

Description

Save codebook information to a file for safe keeping. Depending on the type of codebook (raw or tidy) the file will either be stored as a json-file through write_json or a text table through write.table.

Usage

ns_write_codebook(codebook, path, ...)

## Default S3 method:
ns_write_codebook(codebook, path, ...)

## S3 method for class 'ns_codebook_raw'
ns_write_codebook(codebook, path, ...)

## S3 method for class 'ns_codebook'
ns_write_codebook(codebook, path, sep = "\t", ...)

Arguments

Details

Given the two types of codebooks, writes different types of files.

codebook

- writes a tab-separated table

codebook_raw

- writes a json-file

Value

no return value. Writes a file to path.

Examples

## Not run: 
form_id <- 1100000
my_cb <- ns_get_codebook(form_id)
ns_write_codebook(my_cb, "my/path/codebook_110000.txt")

## End(Not run)

Write meta-data to file

Description

Save meta-data information to a file for safe keeping. The function saves the data in json-format, which best preserves the information.

Usage

ns_write_meta(meta, path, ...)

## Default S3 method:
ns_write_meta(meta, path, ...)

## S3 method for class 'ns_meta'
ns_write_meta(meta, path, ...)

Arguments

Value

no return value. Writes a file to path.

Examples

## Not run: 
form_id <- 1100000
my_meta <- ns_get_meta(form_id)
ns_write_meta(my_meta, "my/path/meta_110000.json")

## End(Not run)