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 [email protected]
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")
library(pubmedR)
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
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:
pmQueryBuild
→ pmQueryTotalCount → pmApiRequest →
pmApi2df), which gives you full control over each
stage;pmCollect(), a
convenience wrapper that chains the whole pipeline in a single call and
optionally enriches the result with citation data.
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
)
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.
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]"
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
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.
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] 862AU also lists collective authors,
in their place among the others, so they count as authors in the
analyses.
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.
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.
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()