scopusflow (Python)¶
A reproducible workflow layer over pybliometrics for Scopus searches.
This is the Python twin of the R package of the same name and follows the same design, so a search written in one language reads much the same in the other.
Get started Try the code-free app
Status
scopusflow is an early release and carries an offline test suite. Its retrieval and abstract drivers are thin layers over pybliometrics, so a short trial run against your installed version is worth doing before a large live harvest.
Why this exists¶
pybliometrics is the mature way to reach the Scopus API from Python. It wraps around ten endpoints and handles the HTTP, cursor pagination, weekly-quota rotation and per-query caching. What it does not provide is a workflow on top of that plumbing, such as a declarative search plan, a single record schema that holds across query types, a resumable harvest with checkpoints, or DOI change-tracking between runs. scopusflow fills that gap, and depends on pybliometrics, re-implementing none of the plumbing it already does well.
| pybliometrics | scopusflow | |
|---|---|---|
| Reach the API (search, retrieval, quota, cursor, cache) | yes | delegates |
| Declarative, reproducible search plan | no | yes |
| One stable record schema across query types | no | yes |
| Resumable, checkpointed harvest of a plan | no | yes |
| DOI extraction and change-tracking between runs | no | yes |
| Annual publication trends without downloading records | no | yes |
| Topic-trend comparison with stability bands | no | yes |
| Batch abstract retrieval, resilient per id | no | yes |
| Trend and top-source/author plots | no | yes |
| Export to reference managers (BibTeX, RIS) | no | yes |
| PRISMA-S search record for a methods section | no | yes |
| Minimal, uniform keyword/reference corpus export | no | yes |
The other Python options are not live alternatives. elsapy was archived as read-only in January 2025, and pyscopus last saw a release in January 2019.
Install¶
scopusflow installs from PyPI with the command below. The optional extras add the figures, the code-free app and parquet files, installed with pip install "scopusflow[plot]", pip install "scopusflow[app]" and pip install "scopusflow[parquet]". The parquet extra installs pyarrow, which write_records() and read_records() need for a .parquet file, the format that keeps a harvest's provenance. The double quotes stop zsh, the default shell on macOS, from reading the brackets as a filename pattern.
pip install scopusflow
A Scopus API key is needed only for the steps that contact the API. pybliometrics keeps it in its configuration file, ~/.config/pybliometrics.cfg, and reads that file only when pybliometrics.init() is called, once in every session. The first call creates the file and asks for your key.
A first search¶
import pybliometrics
import scopusflow as sf
pybliometrics.init() # once per session, before the first search
q = sf.scopus_query("graphene", "supercapacitor", field="TITLE-ABS-KEY")
plan = sf.SearchPlan(q, years=range(2015, 2025), partition="year")
records = sf.fetch_plan(plan, cache_dir="harvest", resume=True)
sf.top(records, by="source")
dois = sf.extract_dois(records)
later = sf.fetch_plan(plan, cache_dir="harvest2")
sf.diff_dois(old=records, new=later)
trend = sf.scopus_trend(q, years=range(2015, 2025))
sf.plot_trend(trend)
sf.scopus_search_report(records, file="search-record.md")
Only the retrieval steps there need a key. Each of them asks the API and spends quota, the second fetch_plan included, because scopusflow bypasses pybliometrics' own response cache unless you pass refresh=False. Everything downstream of them works on records you already hold, and sf.example_records() returns a bundled set of 138 real articles in the harvest schema, so the whole analysis half of the workflow can be tried before you configure anything. It is not a Scopus harvest, since retrieved records may not be redistributed. Get started explains where it does come from.
The guides give worked walk-throughs of each part of the workflow, from designing a query to comparing topics and exporting the result. The API reference documents the full API.
If scopusflow contributes to published work, please cite it. Its citation gives the concept DOI https://doi.org/10.5281/zenodo.21252666, which resolves to the latest release archived on Zenodo.