Skip to contents

An R-package to gather bibliographic data from PubMed.

 

The goal of pubmedR is to gather metadata about publications, grants and
clinical trials from the PubMed database using NCBI REST APIs.

 

https://massimoaria.github.io/pubmedR/

https://github.com/massimoaria/pubmedR

Latest version: 1.0.2.9000, 2026-11-05

 

by Massimo Aria

Full Professor in Social Statistics

PhD in Computational Statistics

Laboratory and Research Group STAD Statistics, Technology, Data Analysis

Department of Economics and Statistics

University of Naples Federico II

email

https://www.massimoaria.com

 

Installation

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

install.packages("devtools")
devtools::install_github("massimoaria/pubmedR")

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

install.packages("pubmedR")

 

Load the package

library(pubmedR)

 

NCBI API key

By default, access to the NCBI API is free and does not strictly require an API key. Without a key, NCBI limits users to 3 requests per second; registered users with an API key are allowed up to 10 requests per second.

To obtain a key, register for a “my ncbi account” (https://account.ncbi.nlm.nih.gov/) and generate one from the “account settings page” (https://account.ncbi.nlm.nih.gov/settings/).

You can pass the key explicitly via the api_key argument of any function, or - preferably - set it once as an environment variable. pubmedR will automatically pick it up from PUBMED_API_KEY or ENTREZ_KEY:

# option 1: pass it explicitly
api_key <- "your API key"

# option 2: set it once per session (or in ~/.Renviron)
Sys.setenv(PUBMED_API_KEY = "your API key")

# no key
api_key <- NULL

 

A brief example

Imagine we want to download a metadata collection of journal articles that (1) use bibliometric approaches, (2) were published in the last two decades, and (3) are written in English.

Since version 0.1.0, pubmedR offers two equivalent workflows:

  • a step-by-step workflow (pmQueryBuild → pmQueryTotalCount → pmApiRequest → pmApi2df), which gives you full control over each stage;
  • a one-step workflow via pmCollect(), a convenience wrapper that chains the whole pipeline in a single call and optionally enriches the result with citation data.

 

One-step workflow: pmCollect()

For most use cases, pmCollect() is the fastest way to go from a query to a bibliometrix-ready data frame. It builds the query, checks the total count, downloads the records, converts the XML into a data frame, and (optionally) adds citation counts and cited references.

library(pubmedR)

M <- pmCollect(
  terms      = "bibliometric*",
  fields     = "Title/Abstract",
  language   = "english",
  pub_type   = "Journal Article",
  date_range = c("2000", "2020"),
  limit      = 2000,
  api_key    = NULL
)

# Query:  bibliometric*[Title/Abstract] AND english[LA] AND
#         Journal Article[PT] AND 2000:2020[DP]
#
# Total records found: 3744
# Records to download: 2000

You can also pass a raw PubMed query string directly:

M <- pmCollect(
  query   = "bibliometric*[Title/Abstract] AND english[LA] AND 2023:2024[DP]",
  limit   = 200
)

Set enrich = TRUE to add citation counts (TC) and cited references (CR) via pmEnrichCitations(). It also looks up every cited PMID, so it takes longer on large collections:

M <- pmCollect(
  terms      = "bibliometric*",
  date_range = c("2023", "2024"),
  limit      = 50,
  enrich     = TRUE
)

 

Step-by-step workflow

If you prefer fine-grained control - for example to inspect the translated query before downloading - you can run the pipeline one stage at a time.

Step 1: Build the query

Instead of writing the Entrez query string by hand, you can use pmQueryBuild() to compose it programmatically from parameters:

query <- pmQueryBuild(
  terms      = "bibliometric*",
  fields     = "Title/Abstract",
  language   = "english",
  pub_type   = "Journal Article",
  date_range = c("2000", "2020")
)

query
# [1] "bibliometric*[Title/Abstract] AND english[LA] AND
#      Journal Article[PT] AND 2000:2020[DP]"

Several values in language or pub_type are combined with OR, as in language = c("english", "italian"). Of course, you can still write the query manually if you prefer:

query <- "bibliometric*[Title/Abstract] AND english[LA] AND Journal Article[PT] AND 2000:2020[DP]"

 

Step 2: Check the effectiveness of the query

Use pmQueryTotalCount() to see how many records PubMed would return, along with the automatically translated query:

res <- pmQueryTotalCount(query = query, api_key = api_key)

res$total_count
# [1] 3744

res$query_translation
# [1] "\"bibliometric*\"[Title/Abstract] AND \"english\"[Language] AND
#      \"journal article\"[Publication Type] AND
#      2000/01/01:2020/12/31[Date - Publication]"

pmCountByYear() shows how those records spread over the years, without downloading them:

pmCountByYear(query, years = 2018:2020)
#   year count
# 1 2018   482
# 2 2019   636
# 3 2020  1004

 

Step 3: Download the collection of document metadata

You can now download the whole collection (or a subset, by lowering limit):

D <- pmApiRequest(query = query, limit = res$total_count, api_key = api_key)

PubMed serves at most 9,999 records per search. If you ask for more, pmApiRequest() splits the query by the date records were added to PubMed and downloads the parts in turn. The records then come in that order, newest first, not in the order of the original search.

pmApiRequest() returns a list with the following elements:

  • data - the XML-structured list containing the bibliographic metadata collection downloaded from PubMed.
  • query - the original query submitted by the user.
  • query_translation - the query as translated and executed by NCBI’s Automatic Terms Translation system.
  • records_downloaded - number of records actually downloaded.
  • total_count - total number of records matching the query.

 

Step 4: Convert the XML object into a data frame

Finally, transform the XML-structured object D into a data frame where rows are documents and columns are field tags compatible with the bibliometrix R package (https://CRAN.R-project.org/package=bibliometrix, https://bibliometrix.org/).

M <- pmApi2df(D, format = "bibliometrix")

dim(M)
# [1] 3744   33

names(M)
#  [1] "AU"        "AF"        "TI"        "SO"        "SO_CO"     "LA"
#  [7] "DT"        "PT"        "DE"        "ID"        "MESH"      "AB"
# [13] "C1"        "CR"        "TC"        "SN"        "J9"        "JI"
# [19] "PY"        "PY_IS"     "VL"        "IS"        "DI"        "PG"
# [25] "GRANT_ID"  "GRANT_ORG" "UT"        "PMID"      "PMCID"     "DB"
# [31] "AU_UN"     "AU_CO"     "AU1_CO"

Setting format = "raw" keeps the same field tags, with the text as PubMed writes it rather than in upper case, and leaves out AU_CO and AU1_CO.

Three fields are worth a closer look:

  • PY is the year of the journal issue. The [DP] tag in a query also matches the electronic publication date, so a query can return documents with a later PY: an article online in 2020 and in an issue of 2021 matches 2000:2020[DP], and has PY 2021. Here this applies to 163 of the 3,744 documents.

  • DT holds only the first publication type, usually “Journal Article” even for a review. PT holds all of them:

      sum(grepl("REVIEW", M$PT))
      # [1] 862
  • AU also lists collective authors, in their place among the others, so they count as authors in the analyses.

 

Fetching records by PMID or DOI

If you already know which articles you want, you can bypass the query step and download records directly by their PubMed identifiers with pmFetchById():

pmids <- c("34813985", "34813456", "34812345")
D <- pmFetchById(pmids = pmids, api_key = api_key)
M <- pmApi2df(D)

pmFetchByDoi() does the same from DOIs, for instance to complete a collection from another database, and lists the DOIs that are not in PubMed:

D <- pmFetchByDoi(c("10.1038/nature14539", "10.9999/not.a.real.doi"))
D$not_found
# [1] "10.9999/not.a.real.doi"

Both return the same structure as pmApiRequest(), so the result can be fed into pmApi2df() exactly the same way.

 

Citation enrichment

PubMed records carry no citation count, so TC is 0 after the download. There are two sources for it:

  • pmCitedBy(pmid) returns the PMIDs of the articles citing the given article. They come from NCBI’s E-Link service, which counts citing articles in PubMed Central.
  • pmICite(pmids) returns citation counts and the Relative Citation Ratio from NIH iCite, built on the larger NIH Open Citation Collection. No API key is needed.

The counts can differ widely:

pmCitedBy(pmid = "25824007")$count
# [1] 31

pmICite("25824007")[, c("pmid", "citation_count", "relative_citation_ratio")]
#       pmid citation_count relative_citation_ratio
# 1 25824007             40                1.517149

For cited references:

  • pmExtractReferences(D) returns one row per reference from the records you already downloaded, with no further requests;
  • pmReferences(pmid) returns the PMIDs referenced by one article, through E-Link, which works only for articles with full text in PubMed Central.

pmEnrichCitations() adds TC, CR (cited references) and NR (their number) to a whole data frame. Pass the downloaded records as P to avoid fetching them again, and choose the source of the counts with tc_source:

M_enriched <- pmEnrichCitations(M, P = D, tc_source = "icite", api_key = api_key)

An article whose count could not be retrieved keeps its TC, with a warning.

Note: citation data from PubMed Central is less comprehensive than commercial databases such as Web of Science or Scopus.

 

An overview of the collection using bibliometrix

Once you have a data frame M, you can use bibliometrix for descriptive and network analyses (https://CRAN.R-project.org/package=bibliometrix, https://bibliometrix.org/).

install.packages("bibliometrix")
library(bibliometrix)

M <- convert2df(D, dbsource = "pubmed", format = "api")
results <- biblioAnalysis(M)
summary(results, k = 10)

# Main Information about data
#
#  Timespan                              2000:2024
#  Sources (Journals, Books, etc)        1525
#  Documents                             3744
#  ...

You can also work in the Biblioshiny app, which can download from PubMed by itself:

biblioshiny()