Query PubMed via the NCBI E-utilities
(esearch + efetch) and return the results as an sm_corpus.
Uses retmax/retstart pagination to retrieve up to n_max records.
Providing an NCBI API key allows up to 10 requests/second instead of 3.
MeSH headings become concepts in the "mesh" vocabulary. Their score
is 1 for a major topic of the article (MajorTopicYN on the descriptor or
one of its qualifiers) and 0 otherwise.
Usage
sm_fetch_pubmed(
query,
n_max = 200L,
api_key = Sys.getenv("NCBI_API_KEY"),
engine = c("native", "rentrez", "auto"),
verbose = TRUE,
call = rlang::caller_env()
)Arguments
- query
PubMed search query string (required).
- n_max
Maximum number of records to return (default 200).
- api_key
NCBI API key. Read from
NCBI_API_KEYenv var by default.- engine
One of
"native"(built-in httr2 client),"rentrez"(use the rentrez package), or"auto"(use rentrez if available, otherwise native).- verbose
Print progress messages?
- call
Caller environment for error reporting.
Value
An sm_corpus object. Its provenance records the search
(query, n_max and engine), so that sm_rebuild_from_cert() can
run it again.
Failed requests
Native requests retry transient server and network failures, and short
announced rate-limit waits. Long waits abort immediately. If a later
page fails, the error inherits from scimapR_fetch_incomplete and holds
the earlier parsed works in rlang::last_error()$partial. Their metadata
records fetch_incomplete with the source, received and expected counts,
and failure reason. If those pages cannot be parsed, partial is NULL.
The default remains an error; an incomplete fetch is never returned as
an ordinary successful result.
Examples
# \donttest{
# Queries the NCBI E-utilities web API.
if (requireNamespace("curl", quietly = TRUE) && curl::has_internet()) {
corpus <- try(sm_fetch_pubmed(query = "bibliometrics[tiab]", n_max = 5))
print(corpus)
}
#> ℹ Searching PubMed for: "bibliometrics[tiab]"
#> ℹ Found 6331 results; fetching 5 records.
#> ℹ Fetched 5 / 5 PubMed records.
#> ✔ Parsed 5 PubMed records into sm_corpus.
#>
#> ── <sm_corpus> ─────────────────────────────────────────────────────────────────
#> Works: 5 | Authors: 31 | Institutions: 0
#> Years: 2026 - 2026
#> Sources (journals): 4
#> Embeddings: none
#> Provenance: pubmed (5)
#> Status: Unlocked (last refreshed: never)
# }