Introduction

openalexR helps you interface with the OpenAlex API to retrieve bibliographic infomation about publications, authors, venues, institutions and concepts with 4 main functions:

• oa_query(): generates a valid query, written following the OpenAlex API syntax, from a set of arguments provided by the user.

• oa_request(): downloads a collection of entities matching the query created by oa_query() or manually written by the user, and returns a JSON object in a list format.

• oa2df(): converts the JSON object in classical bibliographic tibble/data frame.

• oa_fetch(): composes three functions above so the user can execute everything in one step, i.e., oa_query |> oa_request |> oa2df

Installation

You can install the developer version of the openalexR from GitHub with:

install.packages("remotes")
remotes::install_github("massimoaria/openalexR")

You can install the released version of openalexR from CRAN with:

install.packages("openalexR")

Package loading

library(openalexR)
library(dplyr)

Works (think papers, publications)

This paper:

Aria, M., & Cuccurullo, C. (2017). bibliometrix: 
An R-tool for comprehensive science mapping analysis. 
Journal of informetrics, 11(4), 959-975.

is associated to the OpenAlex-id W2755950973. If you know your paper’s OpenAlex ID, all you need to do is passing identifier = <openalex id> as an argument in oa_fetch():

paper_id <- oa_fetch(
  identifier = "W2755950973",
  entity = "works",
  verbose = TRUE
)

## [1] "https://api.openalex.org/works/W2755950973"

## Requesting url: https://api.openalex.org/works/W2755950973

dplyr::glimpse(paper_id)

## Rows: 1
## Columns: 26
## $ id               <chr> "https://openalex.org/W2755950973"
## $ display_name     <chr> "bibliometrix : An R-tool for comprehensive science m…
## $ author           <list> [<data.frame[2 x 10]>]
## $ ab               <chr> "Abstract The use of bibliometrics is gradually exten…
## $ publication_date <chr> "2017-11-01"
## $ relevance_score  <lgl> NA
## $ so               <chr> "Journal of Informetrics"
## $ so_id            <chr> "https://openalex.org/V205292342"
## $ publisher        <chr> "Elsevier"
## $ issn             <list> <"1875-5879", "1751-1577">
## $ url              <chr> "https://doi.org/10.1016/j.joi.2017.08.007"
## $ first_page       <chr> "959"
## $ last_page        <chr> "975"
## $ volume           <chr> "11"
## $ issue            <chr> "4"
## $ is_oa            <lgl> FALSE
## $ cited_by_count   <int> 1618
## $ counts_by_year   <list> [<data.frame[6 x 2]>]
## $ publication_year <int> 2017
## $ cited_by_api_url <chr> "https://api.openalex.org/works?filter=cites:W275595…
## $ ids              <list> [<tbl_df[3 x 2]>]
## $ doi              <chr> "https://doi.org/10.1016/j.joi.2017.08.007"
## $ type             <chr> "journal-article"
## $ referenced_works <list> <"https://openalex.org/W767067438", "https://openalex…
## $ related_works    <list> <"https://openalex.org/W1513692756", "https://openale…
## $ concepts         <list> [<data.frame[3 x 5]>]

oa_fetch() is a composition of functions: oa_query |> oa_request |> oa2df. As results, oa_query() returns the query string including the OpenAlex endpoint API server address (default). oa_request() downloads the bibliographic records matching the query. Finally, oa2df() converts the final result list to a tibble. The final result is a complicated tibble, but we can use show_works() to display a simplified version:

paper_id %>% 
  show_works() %>%
  knitr::kable()

oa_fetch(
  # identifier = "https://doi.org/10.1016/j.joi.2017.08.007", # would also work (PIDs)
  identifier = "doi:10.1016/j.joi.2017.08.007",
  entity = "works"
) %>% 
  show_works() %>%
  knitr::kable()

oa_fetch(
  identifier = c("W2741809807", "W2755950973"),
  # identifier = c("https://doi.org/10.1016/j.joi.2017.08.007", "https://doi.org/10.1016/j.joi.2017.08.007"), # TODO
  entity = "works",
  verbose = TRUE
) %>% 
  show_works() %>%
  knitr::kable()

## [1] "https://api.openalex.org/works?filter=openalex_id%3AW2741809807%7CW2755950973"

## Requesting url: https://api.openalex.org/works?filter=openalex_id%3AW2741809807%7CW2755950973

## About to get a total of 1 pages of results with a total of 2 records.

oa_fetch(
  # identifier = c("W2741809807", "W2755950973"),
  doi = c("10.1016/j.joi.2017.08.007", "https://doi.org/10.1093/bioinformatics/btab727"),
  entity = "works",
  verbose = TRUE
) %>% 
  show_works() %>%
  knitr::kable()

## [1] "https://api.openalex.org/works?filter=doi%3A10.1016%2Fj.joi.2017.08.007%7Chttps%3A%2F%2Fdoi.org%2F10.1093%2Fbioinformatics%2Fbtab727"

## Requesting url: https://api.openalex.org/works?filter=doi%3A10.1016%2Fj.joi.2017.08.007%7Chttps%3A%2F%2Fdoi.org%2F10.1093%2Fbioinformatics%2Fbtab727

## About to get a total of 1 pages of results with a total of 2 records.

oa_fetch(
  identifier = NULL,
  entity = "works",
  title.search = c("bibliometric analysis", "science mapping"),
  cited_by_count = ">50", 
  from_publication_date = "2020-01-01",
  to_publication_date = "2021-12-31",
  search = NULL,
  sort = "cited_by_count:desc",
  endpoint = "https://api.openalex.org/",
  count_only = TRUE,
  verbose = TRUE
)

## [1] "https://api.openalex.org/works?filter=title.search%3Abibliometric%20analysis%7Cscience%20mapping%2Ccited_by_count%3A%3E50%2Cfrom_publication_date%3A2020-01-01%2Cto_publication_date%3A2021-12-31&sort=cited_by_count%3Adesc"

## Requesting url: https://api.openalex.org/works?filter=title.search%3Abibliometric%20analysis%7Cscience%20mapping%2Ccited_by_count%3A%3E50%2Cfrom_publication_date%3A2020-01-01%2Cto_publication_date%3A2021-12-31&sort=cited_by_count%3Adesc

##               count db_response_time_ms                page            per_page 
##                  34                  13                   1                   1

oa_fetch(
  entity = "works",
  title.search = c("bibliometric analysis", "science mapping"),
  cited_by_count = ">50", 
  from_publication_date = "2020-01-01",
  to_publication_date = "2021-12-31",
  sort = "cited_by_count:desc",
  count_only = FALSE
) %>%
  show_works() %>%
  knitr::kable()

Authors

Similarly to work, we can use identifier to pass in authors’ OpenAlex ID.

Example: We want more information on authors with IDs A923435168 and A2208157607.

oa_fetch(
  identifier = c("A923435168", "A2208157607"),
  verbose = TRUE
) %>%
  show_authors() %>%
  knitr::kable()

## [1] "https://api.openalex.org/authors?filter=openalex_id%3AA923435168%7CA2208157607"

## Requesting url: https://api.openalex.org/authors?filter=openalex_id%3AA923435168%7CA2208157607

## About to get a total of 1 pages of results with a total of 2 records.

Example: We want download all authors’ records of scholars who work at the University of Naples Federico II (OpenAlex ID: I71267560) and who have published more than 499 works.

Let’s first check how many records match the query, then set count_only = FALSE to download the entire collection. We can do this by first defining a list of arguments, then adding count_only (default FALSE) to this list:

my_arguments <- list(
  entity = "authors",
  last_known_institution.id = "I71267560",
  works_count = ">499"
  )

do.call(oa_fetch, c(my_arguments, list(count_only = TRUE)))

##               count db_response_time_ms                page            per_page 
##                  24                  20                   1                   1

do.call(oa_fetch, my_arguments) %>% 
  show_authors() %>%
  knitr::kable()

You can also filter by other filters such as display_name, has_orcid, and orcid:

oa_fetch(
  entity = "authors",
  display_name = "Massimo Aria",
  has_orcid = "true"
) %>%
  show_authors() %>%
  knitr::kable()

oa_fetch(
  entity = "authors",
  orcid = "0000-0002-8517-9411"
) %>%
  show_authors() %>%
  knitr::kable()

Institutions

Example: We want download all records regarding Italian institutions (country_code:it) that are classified as educational (type:education). Again, we check how many records match the query then download the collection:

italian_insts <- list(
  entity = "institutions",
  country_code = "it",
  type = "education",
  verbose = TRUE
)

do.call(oa_fetch, c(italian_insts, list(count_only = TRUE)))

## [1] "https://api.openalex.org/institutions?filter=country_code%3Ait%2Ctype%3Aeducation"

## Requesting url: https://api.openalex.org/institutions?filter=country_code%3Ait%2Ctype%3Aeducation

##               count db_response_time_ms                page            per_page 
##                 231                   1                   1                   1

dplyr::glimpse(do.call(oa_fetch, italian_insts))

## [1] "https://api.openalex.org/institutions?filter=country_code%3Ait%2Ctype%3Aeducation"

## Requesting url: https://api.openalex.org/institutions?filter=country_code%3Ait%2Ctype%3Aeducation

## About to get a total of 2 pages of results with a total of 231 records.

## Rows: 231
## Columns: 22
## $ id                        <chr> "https://openalex.org/I861853513", "https://…
## $ display_name              <chr> "Sapienza University of Rome", "University o…
## $ display_name_alternatives <list> "Università degli Studi di Roma \"La Sapien…
## $ display_name_acronyms     <list> NA, "UNIBO", "UNIPD", "UNIMI", NA, NA, "UNI…
## $ international             <list> [<data.frame[1 x 85]>], [<data.frame[1 x 10…
## $ ror                       <chr> "https://ror.org/02be6w209", "https://ror.or…
## $ ids                       <list> [<tbl_df[6 x 2]>], [<tbl_df[6 x 2]>], [<tbl…
## $ country_code              <chr> "IT", "IT", "IT", "IT", "IT", "IT", "IT", "I…
## $ geo                       <list> [<data.frame[1 x 7]>], [<data.frame[1 x 7]>…
## $ type                      <chr> "education", "education", "education", "educ…
## $ homepage_url              <chr> "http://www.uniroma1.it/", "http://www.unibo…
## $ image_url                 <chr> "https://upload.wikimedia.org/wikipedia/en/4…
## $ image_thumbnail_url       <chr> "https://upload.wikimedia.org/wikipedia/en/t…
## $ associated_institutions   <list> [<data.frame[1 x 24]>], [<data.frame[1 x 12…
## $ relevance_score           <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
## $ works_count               <int> 164894, 131451, 130003, 128423, 92207, 87384…
## $ cited_by_count            <int> 10914663, 9871569, 9832758, 9287101, 6087369…
## $ counts_by_year            <list> [<data.frame[11 x 3]>], [<data.frame[11 x 3…
## $ works_api_url             <chr> "https://api.openalex.org/works?filter=insti…
## $ x_concepts                <list> [<data.frame[14 x 5]>], [<data.frame[15 x 5…
## $ updated_date              <chr> "2022-10-06T06:43:34.606290", "2022-10-05T21…
## $ created_date              <chr> "2016-06-24", "2016-06-24", "2016-06-24", "2…

Venues (think journals)

Example: We want download all records regarding journals that have published more than 100,000 works:

big_journals <- list(
  entity = "venues",
  works_count = ">100000",
  verbose = TRUE
)

do.call(oa_fetch, c(big_journals, list(count_only = TRUE)))

## [1] "https://api.openalex.org/venues?filter=works_count%3A%3E100000"

## Requesting url: https://api.openalex.org/venues?filter=works_count%3A%3E100000

##               count db_response_time_ms                page            per_page 
##                  51                   1                   1                   1

dplyr::glimpse(do.call(oa_fetch, big_journals))

## [1] "https://api.openalex.org/venues?filter=works_count%3A%3E100000"

## Requesting url: https://api.openalex.org/venues?filter=works_count%3A%3E100000

## About to get a total of 1 pages of results with a total of 51 records.

## Rows: 51
## Columns: 15
## $ id              <chr> "https://openalex.org/V3121261024", "https://openalex.…
## $ display_name    <chr> "Research Papers in Economics", "ChemInform", "Social …
## $ publisher       <chr> NA, "Wiley", "Social Science Electronic Publishing", N…
## $ issn            <list> NA, <"1431-5890", "0931-7597", "1522-2667">, "1556-50…
## $ issn_l          <list> NA, "0931-7597", "1556-5068", "0302-9743", NA, "0140-…
## $ is_oa           <lgl> NA, FALSE, FALSE, FALSE, NA, FALSE, FALSE, FALSE, FALS…
## $ is_in_doaj      <lgl> NA, FALSE, FALSE, FALSE, NA, FALSE, FALSE, FALSE, FALS…
## $ ids             <list> [<tbl_df[2 x 2]>], [<tbl_df[6 x 2]>], [<tbl_df[3 x 2]…
## $ homepage_url    <chr> "http://www.repec.org/", NA, NA, "http://www.springer.…
## $ relevance_score <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…
## $ works_count     <int> 746088, 721615, 569576, 520657, 483114, 476698, 433782…
## $ cited_by_count  <int> 1651873, 126388, 1271653, 4958308, 1262634, 6961760, 1…
## $ counts_by_year  <list> [<data.frame[11 x 3]>], [<data.frame[11 x 3]>], [<dat…
## $ x_concepts      <list> [<data.frame[22 x 5]>], [<data.frame[12 x 5]>], [<dat…
## $ works_api_url   <chr> "https://api.openalex.org/works?filter=host_venue.id:V…

Concepts (think theme, keywords)

Example: We want to download the records of all the concepts that concern at least one million works:

popular_concepts <- list(
  entity = "concepts",
  works_count = ">1000000",
  verbose = TRUE
)

do.call(oa_fetch, c(popular_concepts, list(count_only = TRUE)))

## [1] "https://api.openalex.org/concepts?filter=works_count%3A%3E1000000"

## Requesting url: https://api.openalex.org/concepts?filter=works_count%3A%3E1000000

##               count db_response_time_ms                page            per_page 
##                 148                   1                   1                   1

dplyr::glimpse(do.call(oa_fetch, popular_concepts))

## [1] "https://api.openalex.org/concepts?filter=works_count%3A%3E1000000"

## Requesting url: https://api.openalex.org/concepts?filter=works_count%3A%3E1000000

## About to get a total of 1 pages of results with a total of 148 records.

## Rows: 148
## Columns: 17
## $ id                         <chr> "https://openalex.org/C41008148", "https://…
## $ display_name               <chr> "Computer science", "Medicine", "Chemistry"…
## $ display_name_international <list> [<data.frame[1 x 185]>], [<data.frame[1 x …
## $ description                <chr> "theoretical study of the formal foundation…
## $ description_international  <list> [<data.frame[1 x 40]>], [<data.frame[1 x 4…
## $ wikidata                   <chr> "https://www.wikidata.org/wiki/Q21198", "ht…
## $ level                      <int> 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0…
## $ ids                        <list> [<tbl_df[5 x 2]>], [<tbl_df[5 x 2]>], [<tb…
## $ image_url                  <chr> "https://upload.wikimedia.org/wikipedia/com…
## $ image_thumbnail_url        <chr> "https://upload.wikimedia.org/wikipedia/com…
## $ ancestors                  <list> NA, NA, NA, NA, NA, NA, NA, [<data.frame[2…
## $ related_concepts           <list> [<data.frame[93 x 5]>], [<data.frame[51 x …
## $ relevance_score            <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
## $ works_count                <int> 41363895, 37697170, 21071084, 17852796, 173…
## $ cited_by_count             <int> 223574731, 385441502, 340750996, 161070175,…
## $ counts_by_year             <list> [<data.frame[11 x 3]>], [<data.frame[11 x …
## $ works_api_url              <chr> "https://api.openalex.org/works?filter=conc…

Other examples

Get all works citing a particular work

We can download all publications citing another publication by using the filter attribute cites.

For example, if we want to download all publications citing the article Aria and Cuccurullo (2017), we have just to set the argument filter as cites = "W2755950973" where “W2755950973” is the OA id for the article by Aria and Cuccurullo.

aria_count <- oa_fetch(
  entity = "works",
  cites = "W2755950973",
  count_only = TRUE,
  verbose = TRUE
) 

## [1] "https://api.openalex.org/works?filter=cites%3AW2755950973"

## Requesting url: https://api.openalex.org/works?filter=cites%3AW2755950973

aria_count

##               count db_response_time_ms                page            per_page 
##                1688                  14                   1                   1

This query will return a collection of 1688 publications. Let’s to download it and then to convert it into a data frame:

oa_fetch(
  entity = "works",
  cites = "W2755950973",
  count_only = TRUE,
  verbose = TRUE
) %>% 
  dplyr::glimpse()

## [1] "https://api.openalex.org/works?filter=cites%3AW2755950973"

## Requesting url: https://api.openalex.org/works?filter=cites%3AW2755950973

##  Named int [1:4] 1688 15 1 1
##  - attr(*, "names")= chr [1:4] "count" "db_response_time_ms" "page" "per_page"

Convert an OpenAlex data frame to a bibliometrix object

The bibliometrix R-package (https://www.bibliometrix.org) provides a set of tools for quantitative research in bibliometrics and scientometrics. Today it represents one of the most used science mapping software in the world. In a recent survey on bibliometric analysis tools, Moral-Muñoz et al. (2020) wrote: “At this moment, maybe Bibliometrix and its Shiny platform contain the more extensive set of techniques implemented, and together with the easiness of its interface, could be a great software for practitioners”.

The function oa2bibliometrix converts a bibliographic data frame of works into a bibliometrix object. This object can be used as input collection of a science mapping workflow.

bib_ls <- list(
  identifier = NULL,
  entity = "works",
  cites = "W2755950973",
  from_publication_date = "2022-01-01",
  to_publication_date = "2022-03-31"
)

do.call(oa_fetch, c(bib_ls, list(count_only = TRUE)))

##               count db_response_time_ms                page            per_page 
##                 240                  10                   1                   1

do.call(oa_fetch, bib_ls) %>% 
  oa2bibliometrix() %>% 
  dplyr::glimpse()

## Rows: 240
## Columns: 39
## $ AU               <chr> "ZHIQUAN LIU;CHRISTOPHER R. MALINOWSKI;MARIA S. SEPÚL…
## $ RP               <chr> "DEPARTMENT OF FORESTRY AND NATURAL RESOURCES, PURDUE…
## $ C1               <chr> "DEPARTMENT OF FORESTRY AND NATURAL RESOURCES, PURDUE…
## $ AU_UN            <chr> "", "", "", "", "", "", "", "", "", "", "", "", "", "…
## $ AU_CO            <chr> "USA;USA;USA", "ITALY;ITALY;MALAYSIA", "CHINA;CHINA;C…
## $ ID               <chr> "ORGANISM;DAPHNIA;NANOTOXICOLOGY;DAPHNIA MAGNA;ECOTOX…
## $ id_url           <chr> "https://openalex.org/W3212020496", "https://openalex…
## $ author           <list> [<data.frame[3 x 10]>], [<data.frame[3 x 10]>], [<da…
## $ publication_date <chr> "2022-03-01", "2022-01-10", "2022-01-01", "2022-03-08…
## $ relevance_score  <lgl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
## $ so_id            <chr> "https://openalex.org/V203465130", "https://openalex.…
## $ publisher        <chr> "Elsevier", "Emerald (MCB UP)", "Elsevier", "Wiley", …
## $ issn             <list> <"0045-6535", "1879-1298">, <"0007-070X", "1758-4108…
## $ url              <chr> "https://doi.org/10.1016/j.chemosphere.2021.132941", …
## $ first_page       <chr> "132941", "2239", "111780", "1129", "113925", NA, "25…
## $ last_page        <chr> "132941", "2261", "111780", "1155", "113925", NA, "25…
## $ volume           <chr> "291", "124", "153", "39", "301", NA, "19", "292", "1…
## $ issue            <chr> NA, "7", NA, "6", NA, NA, "5", NA, NA, NA, NA, NA, NA…
## $ is_oa            <lgl> FALSE, FALSE, TRUE, FALSE, FALSE, FALSE, TRUE, FALSE,…
## $ counts_by_year   <list> [<data.frame[1 x 2]>], [<data.frame[1 x 2]>], [<data…
## $ cited_by_api_url <chr> "https://api.openalex.org/works?filter=cites:W3212020…
## $ ids              <list> [<tbl_df[4 x 2]>], [<tbl_df[2 x 2]>], [<tbl_df[3 x 2…
## $ doi              <chr> "https://doi.org/10.1016/j.chemosphere.2021.132941", …
## $ referenced_works <list> <"https://openalex.org/W321855510", "https://openale…
## $ related_works    <list> <"https://openalex.org/W2040538662", "https://openal…
## $ concepts         <list> [<data.frame[13 x 5]>], [<data.frame[14 x 5]>], [<da…
## $ id_oa            <chr> "W3212020496", "W4205146162", "W3208801174", "W422099…
## $ CR               <chr> "https://openalex.org/W321855510;https://openalex.org…
## $ TI               <chr> "EMERGING TRENDS IN NANOPARTICLE TOXICITY AND THE SIG…
## $ AB               <chr> "NANOPARTICLE PRODUCTION IS ON THE RISE DUE TO ITS MA…
## $ SO               <chr> "CHEMOSPHERE", "BRITISH FOOD JOURNAL", "RENEWABLE & S…
## $ DT               <chr> "JOURNAL-ARTICLE", "JOURNAL-ARTICLE", "JOURNAL-ARTICL…
## $ DB               <chr> "openalex", "openalex", "openalex", "openalex", "open…
## $ JI               <chr> "V203465130", "V99313352", "V68497187", "V102896891",…
## $ J9               <chr> "V203465130", "V99313352", "V68497187", "V102896891",…
## $ PY               <int> 2022, 2022, 2022, 2022, 2022, 2022, 2022, 2022, 2022,…
## $ TC               <int> 9, 9, 8, 8, 7, 7, 7, 6, 6, 5, 5, 5, 4, 4, 4, 4, 4, 4,…
## $ SR_FULL          <chr> "ZHIQUAN LIU, 2022, CHEMOSPHERE", "PAOLO BIANCONE, 20…
## $ SR               <chr> "ZHIQUAN LIU, 2022, CHEMOSPHERE", "PAOLO BIANCONE, 20…