Count 'Scopus' results for a query

Retrieves only the total number of records matching a query, without downloading them. This is the inexpensive way to size a retrieval before committing quota. The count can guide how to partition a scopus_plan(), or simply report how large a topic is.

Usage

scopus_count(
  query,
  years = NULL,
  field = NULL,
  view = c("STANDARD", "COMPLETE"),
  api_key = NULL,
  inst_token = NULL
)

Arguments

query

Character scalar. The base search expression.

years

Optional integer vector of publication years to restrict to.

field

Optional 'Scopus' field tag to wrap the query in (see scopus_plan()).

view

Either "STANDARD" or "COMPLETE". COMPLETE adds an authkeywords column to scopus_fetch()/scopus_fetch_plan() output (see scopus_records()) at no extra cost beyond COMPLETE's own smaller page size, which already means more requests, and so more quota, for the same number of records.

api_key, inst_token

Optional credentials, resolved by default from options or environment variables (see scopus_has_key()).

Value

A single number giving the total number of matching records, or NA when the API reports no total. It is returned as a double so that very large totals are represented exactly rather than overflowing, with the parsed quota (see scopus_quota()) attached as the quota attribute so a workflow can pace itself off a count.

API access

This function performs a network request and therefore requires a valid API key and internet access. When no key is configured it raises a scopus_error_no_key condition, and other failures raise typed scopus_error subclasses such as scopus_error_rate_limit. A tryCatch() around the call lets a workflow handle these gracefully.

Examples

if (FALSE) { # scopusflow::scopus_has_key()
scopus_count("graphene supercapacitor", years = 2015:2024,
             field = "TITLE-ABS-KEY")
}
# The offline companion, which needs no key: one number with the parsed
# quota attached. The bundled corpus of real articles is a complete harvest
# of its own query, so its row count is the total that query returned. The
# quota attribute is parsed from real response headers by scopus_quota(),
# so it cannot drift from what a live call attaches.
resp <- httr2::response(
  status_code = 200,
  headers = list(
    `X-RateLimit-Limit` = "20000",
    `X-RateLimit-Remaining` = "19987",
    `X-RateLimit-Reset` = "1700000000"
  )
)
n <- nrow(example_records)
attr(n, "quota") <- scopus_quota(resp)
n
#> [1] 138
#> attr(,"quota")
#> attr(,"quota")$limit
#> [1] 20000
#> 
#> attr(,"quota")$remaining
#> [1] 19987
#> 
#> attr(,"quota")$reset
#> [1] "2023-11-14 22:13:20 UTC"
#> 
#> attr(,"quota")$status
#> [1] NA
#> 
#> attr(,"quota")$retry_after
#> [1] NA
#>