scopus-search

name

scopus-search

description

Search Scopus and retrieve paper metadata via pybliometrics. Use whenever the user wants to find papers, build a literature corpus, get abstracts, retrieve references, or prepare data for bibliometric analysis. Triggers: "search Scopus", "find papers on", "literature search", "Scopus query", "get abstracts", "download paper metadata", "bibliometric data", "co-citation", "knowledge graph", pybliometrics, or any academic paper discovery task. Also triggers when filtering by journal tier (ABDC, AJG, FT-50) — integrates with biz-journals skill.

Scopus Search

Search Scopus via pybliometrics, export structured JSON.

Prerequisites

pybliometrics must be installed with API keys in ~/.config/pybliometrics.cfg. If import fails, walk the user through pip install pybliometrics and config creation.

Intent → Endpoint Mapping

Choose endpoint(s) based on what the user actually needs. Not every search requires AbstractRetrieval.

Intent	Endpoint	View/Mode	Rationale
Paper list, lit table, "find papers on X"	ScopusSearch	COMPLETE	Has abstract, keywords, affiliations, citations, funding. One call.
Abstracts for known DOIs/EIDs	AbstractRetrieval	META_ABS	Direct lookup, no search needed.
Author keywords, subject areas, funding detail	AbstractRetrieval	FULL	authkeywords null in META_ABS. FULL has subject_areas, funding, authorgroup.
Co-citation / bibliographic coupling	ScopusSearch + AbstractRetrieval	REF	REF has structured per-reference DOIs, citedbycount, author IDs.
Full metadata + reference strings	ScopusSearch + AbstractRetrieval	FULL	References with fulltext citation strings, plus all metadata.
References for a single paper	AbstractRetrieval	REF	Single lookup by DOI/EID.

Read references/reference.md for the field-by-view matrix and query syntax.

Workflow

Phase 1: Query Building (interactive)

1. Ask: topic, time period, journal tiers, metadata depth
2. Draft Scopus query (see references/reference.md for syntax and patterns)
3. Test: python scripts/search_scopus.py --query '...' --max-results 5
4. Show results, iterate until user is satisfied
5. Confirm: final query, result count, endpoint/view choice, output folder name

When the user wants journal-tier filtering, use the biz-journals skill to generate the ISSN clause and combine with AND.

Phase 2: Retrieval (automated)

Run the appropriate script based on the intent mapping above:

ScopusSearch only (most common — paper list, lit review):

python scripts/search_scopus.py --query '<query>' --max-results 0 --output-dir '<folder>'

When --output-dir is passed, saves scopus_results.json + search_metadata.json instead of printing to stdout.

AbstractRetrieval (when deeper metadata needed):

python scripts/retrieve_abstracts.py \
  --query '<query>' \
  --view REF \
  --output-dir '<folder>'

Report: papers retrieved, file location, any errors or view fallbacks.

Troubleshooting

Error	Fix
"not authorized"	VPN on? Scripts fall back automatically.
400 / syntax error	Check parentheses, AND placement, field codes. PUBYEAR AFT not PUBYEAR >.
Empty results	Remove DOCTYPE(ar), broaden keywords, remove date filter.
Rate limited (429)	Automatic retry with backoff. Reduce --max-results if persistent.

For script options: python <script> --help