gtR

Installation

You can install the package from GitHub using the following code:

remotes::install_github("shanej90/gtR")

How it works

gtR simplifies the process of accessing the UKRI Gateway to Research API.

Currently, it lets you:

  • View a list of endpoints (gtr_endpoints).
  • View a list of resource combinations used in certain functions (gtr_combinations).
  • Get configuration details for said endpoints (get_configs()).
  • Query the API using get_resources(). This allows to return all results for a given ‘resource’ (eg, project, organisation), or resources linked to a specific entity (eg, all projects for an organisation). It also let’s you specify whether you want to return all pages or specific ones, or filter your results using search terms.
  • There are also legacy functions that ‘compartmentalise’ the functionality offered by get_resources(). These allow you to check all results for a given resource query_resource_all() or those that are linked to a specific entity (query_resource_combination()). These legacy functions also provide the option to return metadata about your query instead of just the ‘actual’ results.

Examples

NB I won’t show some actual data outputs as there are some hideously long ID strings in there.

You want to try and identify the University of Exeter’s record in the API.


library(gtR)

data <- get_resources(resource = "organisation", page_nums = 1, size = 10)

You can’t see Exeter in here. However, you’re only looking at the first page. You could try and return more results per page, or try a different page, but doing this randomly wouldn’t be very efficient. What if we try searching specifically for the term “Exeter”?


#return configuration for organisation records to look up field codes to search against

org_config <- get_configs("organisation")

org_config$fields
#>          code       description searchable sortable searchedByDefault
#> 1       org.n Organisation Name       TRUE     TRUE              TRUE
#> 2   org.pro.t    Project Titles       TRUE    FALSE             FALSE
#> 3 org.orcidId          ORCID iD       TRUE    FALSE              TRUE
#> 4   org.pro.a Project Abstracts       TRUE    FALSE             FALSE
#> 5       score         Relevance      FALSE     TRUE             FALSE

#so we can see we need to search against "org.n" to look up the name.
#The configuration file shows this is searched anyway, so we don't need to reference the code, but will for completeness

final_result <- get_resources("organisation", size = 30, search_term = "Exeter", search_fields = "org.n")

Success (third row)!