SPB Git

Repository Public Research preview

sources.md 4.5 KB

# Sources, coverage and limits

Observed on 2026-11-10. Services change: node scripts/scholarly.mjs status shows the configuration in use and, after the first OpenAlex call, the budget left.

# What each service is used for

Service Used for Account Cost
Crossref (api.crossref.org) DOI metadata, search, deposited reference lists, retraction and correction notices none free
doi.org (content negotiation) DOIs of every agency, including DataCite (arXiv, Zenodo, datasets); registry BibTeX none free
arXiv (export.arxiv.org) preprint lookup and search, published DOI recorded by authors none free, one request per 3 s
OpenAlex (api.openalex.org) citing works, related works, author works, open-access locations, retraction flag optional key small free budget

Commands that never touch OpenAlex: verify-doi, resolve, verify-bib, parse-bib, search (default source), get without --enrich, arxiv, references --source crossref, cite, bibtex, retractions --no-openalex. Plain references uses Crossref and falls back to OpenAlex only when the publisher deposited no list.

Commands that need OpenAlex: citations, related, author, oa (except for arXiv ids), get --enrich, search --source openalex, references --source openalex, and retractions by default (one single-record lookup per DOI).

# The OpenAlex budget

Without a key, OpenAlex gives all clients behind one IP address a shared daily allowance. On the test date it was 0.10 USD per day, with a single-record lookup priced at 0.0001 USD and a search or list at 0.001 USD: about a hundred list calls a day, shared with everyone on the same network. When it runs out, OpenAlex answers HTTP 429 and the tool returns the error code rate_limited. Verification is unaffected: it runs on Crossref, arXiv and doi.org.

OpenAlex offers free keys with a larger allowance. Getting one requires an e-mail address, so it is the user's decision: tell them the option exists, and do not register on their behalf. When they have a key, they set OPENALEX_API_KEY in the environment of the tool.

# Coverage

  • Crossref: journal articles and proceedings from publishers that register DOIs with it; good for most journals since the 1990s and for digitised back files. Weak for books, book chapters of small presses, theses, reports, working papers and many regional journals.
  • DataCite via doi.org: arXiv, Zenodo, institutional repositories, datasets. Lookup by DOI only; no search through this tool.
  • arXiv: physics, mathematics, computer science, statistics, quantitative finance, economics and neighbouring fields.
  • OpenAlex: the broadest index of the four, built by aggregation. Author names and affiliations can be noisy; author profiles sometimes merge or split people.

Not covered at all: full text, PubMed-only records without a DOI (use get pmid:<n> through OpenAlex when it has them), legal materials, patents, most grey literature.

# Reference lists

references <doi> returns the list the publisher deposited with Crossref. Many publishers deposit them; some do not, and the list is then empty. Entries without a DOI are raw strings as deposited, sometimes with errors. --source openalex returns only the references OpenAlex could match to a work it indexes, so it can be shorter than the true list.

# Retraction data

Crossref update notices carry type values such as retraction, correction, expression_of_concern, with the DOI and date of the notice; since Crossref incorporated the Retraction Watch database, many notices carry source: retraction-watch. OpenAlex exposes a boolean is_retracted. The tool reports retracted when either says so. Both lag reality and both have gaps: no_notice is an absence of evidence.

# Request behaviour

  • Client name: scholarly-mcp/1.0. No name, address, host name or project detail.
  • SCHOLARLY_MAILTO, when set by the operator, is added as mailto= to Crossref and OpenAlex requests only (their "polite pool" convention). It is unset by default.
  • Per-host limits built in: Crossref 3 concurrent requests, OpenAlex 2, arXiv 1 with a 3 s gap, doi.org 3.
  • Timeout 20 s (SCHOLARLY_TIMEOUT_MS). HTTP 429 and 5xx are retried up to three times with backoff; a Retry-After above 30 s is not waited for.
  • Answers are cached in memory for 15 minutes within one process. Each command-line run is a new process, so nothing persists between runs.
  • A registry outage produces error, upstream_error, rate_limited or timeout. It is never turned into not_found.
Files main
Menu

Theme