Query the Scopus API

scopus_api_key() finds the Elsevier key;
scopus_request() prepares a request (not sent);
scopus_get_page() fetches and parses one page;
scopus_search() fetches all the pages of a query;
scopus_quota() reads the remaining quota from a response.

Usage

scopus_api_key()

scopus_request(
  url,
  query = list(),
  api_key = scopus_api_key(),
  insttoken = NULL,
  max_tries = 5L
)

scopus_get_page(
  url,
  query = list(),
  api_key = scopus_api_key(),
  insttoken = NULL,
  max_tries = 5L,
  pause = 0.2
)

scopus_search(
  query,
  count = 25L,
  view = NULL,
  fields = NULL,
  api_key = scopus_api_key(),
  insttoken = NULL,
  max_tries = 5L,
  pause = 0.2,
  paging = c("auto", "cursor", "start"),
  max_pages = Inf,
  on_page = NULL
)

scopus_quota(resp)

Arguments

url: Character. Complete URL, or a route relative to https://api.elsevier.com.
query: Named list of query parameters. In scopus_search(), a Scopus query string such as "SRCID(123) AND PUBYEAR IS 1990".
api_key: Character. By default scopus_api_key().
insttoken: Character or NULL. Institutional token, if the key needs one outside the institution's network.
max_tries: Integer. Attempts per page.
pause: Numeric. Minimum seconds between two requests.
count: Integer. Results per page (25 for the view COMPLETE).
view: Character or NULL, e.g. "COMPLETE".
fields: Character or NULL. Fields to return, separated by commas.
paging: How to walk through the pages: "auto" (the cursor, or start if the key may not use it), "cursor" or "start".
max_pages: Numeric. Maximum number of pages.
on_page: Function called with each table of results and its page number, or NULL. See api_paginate().
resp: An httr2_response from Elsevier.

Value

scopus_api_key(): a string. scopus_request(): an httr2_request. scopus_get_page(): the parsed JSON (data frames where possible), or NULL after repeated failures. scopus_search(): the list returned by api_paginate(), items being a data.table. scopus_quota(): a list with limit, remaining and reset.

Details

Elsevier limits a key by the week (20,000 requests for the Scopus Search API) and by the second (9 requests). scopus_search() stays below the latter with a pause of 0.2 s.

Exhausting the quota is not a transient failure: a 429 with the header X-ELS-Status: QUOTA_EXCEEDED stops the run at once, saying when the quota resets, as does a key refused with 401 or 403 (the check of the network or the key cannot be retried away). Other 429 and 5xx responses are retried.

Paging. The cursor is the way to walk through long result sets, but Elsevier restricts it by key and network (HTTP 403, "Use of the cursor parameter is restricted", observed on 2026-11-09 outside the institutional network; it works on the VPN). With paging = "auto", scopus_search() then falls back on start. An error from scopus_get_page() includes the explanation sent by Elsevier.

scopus_get_page() takes over fetch_scopus_page() (building_elsevier_database, eea_history), and the behaviour of the first of these copies. It also replaces scopus_get() (eea_history), which returned the response and let the caller check the status.

The key travels in a header, so it does not appear in URLs or logs.

References

Elsevier Developer Portal, API key settings. https://dev.elsevier.com/api_key_settings.html

Examples

if (FALSE) { # \dontrun{
options(politecollect.user_agent = "my_project (me@example.org)")
res <- scopus_search("SRCID(20628) AND PUBYEAR IS 1990", max_pages = 1)
res$items
} # }