README.md

In KTH-Library/kthapi: Data from KTH APIs

kthapi

The goal of the kthapi R package is to provide an API wrapper for some of the APIs used at KTH, The Royal Institute of Technology, which can be used directly in R.

The KTH APIs are described here:

https://www.kth.se/api/anvand-data-fran-kth-1.57059

The KTH APIs provide information about employee profiles, published web content, places, course schemas and program catalogues. This R package interfaces with the API, making data available to use directly from R.

Installation

You can install the development version of kthapi from GitHub with:

#install.packages("devtools)
devtools::install_github("KTH-Library/kthapi", dependencies = TRUE)

Example usage

This API wrapper / client is pre-configured with a set of API endpoints:

library(kthapi)
library(knitr)
suppressPackageStartupMessages(library(dplyr))

This is a basic example which shows you how to make a lookup using the v 1.1 “legacy” Profiles API, where we get contact information for a KTH employee using an account name:

profile <- 
  kth_profile_legacy("tjep") %>% 
  .$content 

# inspect this record
profile %>% glimpse()
#> Rows: 1
#> Columns: 12
#> $ givenName          <chr> "Tobias"
#> $ familyName         <chr> "Jeppsson"
#> $ url                <chr> "https://www.kth.se/profile/tjep"
#> $ email              <chr> "[e-mail]"
#> $ image              <chr> "https://www.kth.se/files/avatar/tjep"
#> $ telephone          <chr> "087907106"
#> $ jobTitle           <chr> "BIBLIOMETRISK ANALYTIKER"
#> $ `jobTitle-en`      <chr> "BIBLIOMETRIC ANALYST"
#> $ workLocation       <chr> "OSQUARS BACKE 31"
#> $ worksFor.url       <chr> "https://www.kth.se/directory/t/tr/trac"
#> $ worksFor.name      <chr> "PUBLICERINGENS INFRASTRUKTUR"
#> $ `worksFor.name-en` <chr> ""

# pivot into long format and display as a table
profile %>% t() %>% as.data.frame() %>%  
  cbind(rownames(.)) %>% setNames(nm = c("value", "key")) %>% as_tibble() %>%
  select(key, value) %>%
  kable()

| key | value | |:-----------------|:-----------------------------------------| | givenName | Tobias | | familyName | Jeppsson | | url | https://www.kth.se/profile/tjep | | email | [e-mail] | | image | https://www.kth.se/files/avatar/tjep | | telephone | 087907106 | | jobTitle | BIBLIOMETRISK ANALYTIKER | | jobTitle-en | BIBLIOMETRIC ANALYST | | workLocation | OSQUARS BACKE 31 | | worksFor.url | https://www.kth.se/directory/t/tr/trac | | worksFor.name | PUBLICERINGENS INFRASTRUKTUR | | worksFor.name-en | |

# NB: some valid account names do not return data
tryCatch(kth_profile_legacy("markussk"), error = function(e) e)
#> <KTH API call for markussk>
#> # A tibble: 0 × 10
#> # … with 10 variables: givenName <chr>, familyName <chr>, url <chr>,
#> #   email <chr>, image <chr>, telephone <chr>, jobTitle <chr>,
#> #   jobTitle-en <chr>, worksFor <list>, workLocation <chr>

More examples

This is a basic example which shows how to make a lookup using the authenticated Profiles API:

profile <- 
  kth_profile(username = "tjep") %>%
  .$content

# organizational belonging
profile$worksFor$items %>% 
  tibble::as_tibble() %>%
  select(path, name, nameEn) %>%
  knitr::kable()

| path | name | nameEn | |:----------|:-----------------------------|:------------| | t/tr | KTH BIBLIOTEKET | KTH LIBRARY | | t/tr/trac | PUBLICERINGENS INFRASTRUKTUR | |

# corresponding "slugs"
profile$worksFor$items$path
#> [1] "t/tr"      "t/tr/trac"

# displayname used in ABM app
kth_displayname("tjep", type = "username")
#> [1] "Tobias Jeppsson (tjep)"

# NB: this (authenticated API call) does not throw an error for non-employees
kth_displayname("markussk", type = "username")
#> [1] "Markus Skyttner (markussk)"

For more usage examples, please see the package vignettes.

KTH-Library/kthapi documentation built on June 27, 2023, 9:27 p.m.