Scopus API Toolkit

把 dev.elsevier.com 官方 API 封装成一条命令就能跑通的本地工具链。
特点：零依赖（只用 Python 标准库，不用装 requests/pybliometrics）、自动分页、自动处理配额与 429、输出直接可用。

何时使用

• 「帮我检索某个主题的 Scopus 文献，导出 Excel/CSV」
• 「查这篇论文的参考文献列表 / 被引次数」
• 「这个作者的 H-index 和发文数」「机构发文量」「期刊 CiteScore」
• 「按年份/学科/期刊统计某个领域的分布」（分面 facets）
• 为 bibliometrix（R）、VOSviewer、CiteSpace 准备数据

环境

• 脚本：scripts\scopus_client.py
• 解释器：python（本机自动解析）
• 凭据：本机提前配置，自动从 C:\Users\{当前用户名}\.env（变量名类似 Scopus_Api_Key）读取，如果没有凭据（key），需要中断过程，提示用户自行到Scopus.com官网注册获取api key， 不要把它写进任何 skill 文件或命令里。详见 references/credentials.md

> 路径含空格/中文，命令里一律用英文引号包住。输出目录建议用 -o "D:\...\文件名.csv" 而非 /tmp（Git Bash 的 /tmp 与 Windows Python 看到的路径不一致）。

输出文件夹规范（按数据源分文件夹，务必遵守）

同一工作区可能同时用 Scopus / OpenAlex 等多个数据源导出，所有导出和派生产物必须按数据源分文件夹存放：

<工作目录>/                  # 默认当前工作区根目录，或用户指定的目录
├── scopus/                  # Scopus 检索导出的原始数据（CSV/JSON）← 本技能的 -o 默认落位
├── openalex/                # OpenAlex 导出的原始数据
├── vosviewer/
│   ├── scopus/              # 基于 Scopus 数据生成的 map/network/截图
│   └── openalex/            # 基于 OpenAlex 数据生成的 map/network/截图
└── scripts/                 # 一次性转换脚本（可选）

• 用户没给输出路径时，search/export 的 -o 默认写到当前工作目录的 scopus/ 子文件夹；用户显式给了路径以用户为准。
• 排序提示：--sort=-citedby-count 可按被引次数降序取 Top N（「导出被引最高的前 N 条」场景），--sort=-pubyear 按出版年降序；--sort citedby-count 为升序。

快速上手

S=".\scripts\scopus_client.py"

# 1) 先验配额与连通性（任何任务的第一步，只耗 1 次额度）
python "$S" quota

# 2) 先看规模再决定拉多少（1 次额度拿到命中总数）
python "$S" total -q 'TITLE-ABS-KEY("solid state battery") AND PUBYEAR > 2020'

# 3) 检索导出
python "$S" search -q 'TITLE-ABS-KEY("solid state battery") AND PUBYEAR > 2020' \
    -n 500 -f csv -o "D:\lit\battery.csv"

命令一览

全局参数（可放在任意位置）：--api-key --insttoken --env-file --timeout --min-interval --max-retries -v

导出「和 Scopus 网页一模一样」的 CSV（含参考文献）

当需求是「格式要和 Scopus 导出的结果一致」「要包含参考文献」（导师要附件、投稿附件、复现别人的处理流程、喂 bibliometrix::convert2df），
用 export 而不是 search：search 的 CSV 是给 VOSviewer/分析用的精简拍平表，列名称与列数都不同。

# 200 条，被引降序，含全部参考文献（默认行为）
python "$S" export -q 'TITLE-ABS-KEY(electrochem*) AND PUBYEAR > 2021' \
  -n 200 --sort -citedby-count -o "D:\lit\electrochem_200.csv"

# 只要元数据不要参考文献：不耗 abstract 配额，速度快 100 倍
python "$S" export -q '...' -n 200 --no-refs -o quick.csv

# 参考文献超长的综述：每篇只留前 50 条，避免撑爆 Excel 单元格
python "$S" export -q '...' -n 200 --refs-cap 50 -o capped.csv

# 不联网重建：复用上次存下的检索结果（0 次请求，改列/改截断都不必重新检索）
python "$S" export --from-json raw_search.json -n 200 -o same.csv

43 列、列序与列名完全对齐 Scopus 官网 Export → CSV：
Authors / Author full names / Author(s) ID / Title / Year / Source title / Volume / Issue / Art. No. /
Page start / Page end / Page count / Cited by / DOI / Link / Affiliations / Authors with affiliations /
Abstract / Author Keywords / Index Keywords / Molecular Sequence Numbers / Chemicals/CAS / Tradenames /
Manufacturers / Funding Details / Funding Text 1–3 / References / Correspondence Address /
Editors / Publisher / ISSN / ISBN / CODEN / PubMed ID / Language of Original Document /
Abbreviated Source Title / Document Type / Publication Stage / Open Access / Source / EID

字段来源分两层（这也是为什么不能只用一次 search）：

配额估算：导出 200 条 ≈ ceil(200/25)=8 次 search + 200 次 abstract-retrieval（weekly 配额各自独立计）。

几个实测细节，直接影响成品质量：

• FULL view 一次就带回全部参考文献（item.bibrecord.tail.bibliography.reference[] 的 ce:source-text 正是网页上显示的那串著录文本）。不需要走 REF view 的 40 条分页，也就绕开了「末尾一条取不到 / startref 越界报 400」的老坑。
• References 单元格按 Scopus 写法拼：1) 著录文本; 2) 著录文本; ...，分号分隔、不换行。
• Link 列用的是 scopus.com/inward/record.uri?eid=...&partnerID=40（网页导出的形式），不是 API 地址。
• ISSN 补连字符（00280836 → 0028-0836）；Page count 由起止页相减得出；文章号型文献（无页码）页留空、Art. No. 有值 —— 与网页导出一致。
• 详情缓存写 <输出名>.fullcache.jsonl，中断后重跑同命令会跳过已抓的篇目（--cache 可指定）。这是 200 条以上批量导出的关键，别删。
• --from-json 可直接吃 search -f json 的产物（也兼容原始响应体），跳过检索层；配合上面的详情缓存，常见场景（改 --refs-cap、重出表）0 次请求即可完成。

> ⚠️ Excel 单元格上限 32767 字符。综述类文献的 References 可能 4–5 万字符，CSV 里数据完整，但 Excel 打开会截断显示。要进 Excel 就加 --refs-cap，或改用「一条参考文献一行」的长表结构。

导出 bibliometrix 直读的 BibTeX（-f bib）

背景：Scopus 的 API 没有 BibTeX 端点（网页上的 Export→BibTeX 是前端转换），而 bibliometrix 5.x 的 convert2df(dbsource="scopus") 只吃 BibTeX、不认 CSV。所以脚本按 Scopus BibTeX 规范自己生成，字段名逐条对齐 bibliometrix 的 data/bibtag.rda 映射。

# 一步生成 .bib
python "$S" export -q 'TITLE-ABS-KEY(bibliometric*)' -n 200 -f bib -o "D:\lit\biblio\scopus_200.bib"

# 接着就能直接进 bibliometrix
Rscript -e "M <- bibliometrix::convert2df('D:/lit/biblio/scopus_200.bib', dbsource='scopus', format='bibtex'); print(dim(M))"

四个坑（都是实测）：

• 与 CSV 共用详情缓存（默认 <输出>.fullcache.jsonl）：默认按输出文件名走，所以「CSV 和 .bib 输出到不同文件名」时要显式 --cache 指定同一个文件。实测复用后 3 条记录只发 2 次请求（1 次检索 + 1 页），不复用是 5 次。
• references 末尾必须留一个字符：bibliometrix 解析时无条件截掉最后一个字符，所以脚本在最后补一个 .；不补就会吃掉最后一条引文。
• Scopus 的参考文献是自由文本（作者, 题名, 刊名, 年, 卷, 页），bibliometrix 的共被引解析对 WoS 式 作者, 年, 刊名 更友好。要做共被引网络，最好同时有一份 WoS 导出，或接受 Scopus 原样的解析效果。
• -f bib 同样支持 --no-refs（跳过 FULL view，快 100 倍但 CR 为空）、--refs-cap、--from-json、--cache，语义与 CSV 完全一致。

本机实证的能力边界（2026-10-26 实测）

配额与限流（重要）

• 配额按单个 API分别计算，每周重置一次；quota 命令可读当前剩余。
• 各搜索类 API 限速 2–10 次/秒。脚本默认最小间隔 0.15s（--min-interval），撞到 429 会自动退避重试。
• 省额度的最佳实践：先用 total 看规模 → 用 --view COMPLETE 一次拿全字段，别为每篇再单独请求摘要 → 需要摘要时优先从 COMPLETE 检索结果里取（dc:description）。
• 一次 200 条的检索 ≠ 200 次额度消耗：count=200 的 STANDARD 检索只算 1 次。

已踩过的坑（须避免）

1. 端点必须带 /content：正确根是 https://api.elsevier.com/content/search/scopus，漏了就是 404。
2. REF view 只返回前 40 条参考文献，会静默截断；且 startref + refcount 越过 @total-references 时不返回空列表，而是直接 400 INVALID_INPUT。脚本已按 total - startref 保守分页（所以 67 条只能取到 66 条，末尾那条通常不可解析）。
3. start/count 分页上限累计 5000 条，再多必须 --cursor（cursor 模式下每页强制 25）。单次查询上限约 20000 条，超了要按年份切片。
4. STANDARD 与 COMPLETE 字段差异大：STANDARD 没有摘要/关键词/完整作者名单，只有第一作者和第一单位；要这些必须 --view COMPLETE（代价：每页最多 25 条）。
5. 斜杠要编码：DOI 里的 / 在 URL 中要写 %2F，脚本已处理，但 raw 手写路径时需留意。
6. stdout 别被污染：不带 -v 时脚本不打印配额，保证 | python -c 管道能直接 json.loads。
7. search 的 CSV ≠ Scopus 网页导出的 CSV：前者是 34 列的精简拍平表（列名小写、无 References/Funding Text/Correspondence），后者是 43 列官方格式。用户说「要和 Scopus 导出一致」时一律用 export，别拿 search 的 CSV 交差。
8. FULL view 的响应外面包了一层 abstracts-retrieval-response：解析时先下钻这一层，否则取到的全是空值（parse_full_record 已兼容两种入参）。
9. --sort -citedby-count 的短横线：argparse 会把 -citedby-count 当成新选项而报 expected one argument；脚本已做 --sort=-citedby-count 的等价改写，两种写法都能用。
10. 给 bibliometrix 用必须 -f bib：convert2df(dbsource="scopus") 只认 BibTeX，喂 CSV 会报列错或字段全空（bibliometrix 5.x 的明确变更）。API 取数链路是 export -f bib → convert2df(..., format="bibtex")。
11. 不传 --sort 拿到的不是"最相关"，是"最新"：Scopus API 缺省按 coverDate 倒序返回。要按相关度取前 N 条必须显式 --sort relevancy。已实测：同一检索式，不带 sort 的前 3 条是 2027 年 12 月、被引 0 的新论文；带 relevancy 的前 3 条才是被引较高的主题核心文献。凡用户说"最相关/highest relevance/top N by relevance"，一律加这个参数。
12. export 的速度瓶颈在逐篇 FULL 详情：约 0.25–0.5 条/秒，1000 条约 15–35 分钟。详情缓存 <输出>.fullcache.jsonl 让 CSV 与 BibTeX 共用，中途断了直接重跑同一条命令即可续上（已缓存的不会再扣配额）。

更多

• references/query-syntax.md —— 检索式语法与全字段码（TITLE-ABS-KEY、AFFILCOUNTRY、SRCTYPE、DOCTYPE、OPENACCESS…）
• references/api-reference.md —— 端点/参数/view 字段清单/配额表/错误码
• references/recipes.md —— 典型工作流：年度趋势、作者画像、参考文献网络、对接 VOSviewer/bibliometrix
• references/credentials.md —— 凭据、校外访问 insttoken、合规与署名要求