europepmc-search
Europe PMC RESTful Web Service 多源文献聚合检索原子 skill。一次调用同时召回 PubMed + PMC + AGRICOLA + CABI + 预印本(bioRxiv / medRxiv / ChemRxiv 等)+ 灰色文献,自动按 PMID/PMCID/DOI 三级去重,返回完整元数据(含全文 OA 链接、citations metadata、grants
SKILL.mdarchives/user-installed-skills/europepmc-search/5eec9d3036d956eb/europepmc-search/SKILL.md
GitHubeuropepmc-search
Europe PMC RESTful Web Service 的薄封装。一次请求 = 多源召回:PubMed(MED)、PubMed Central(PMC)、AGRICOLA(AGR)、CABI(CBA)、预印本(PPR,涵盖 bioRxiv/medRxiv/ChemRxiv/arXiv 生命科学子集)、专利(PAT)、ETHOS 论文集等。
1. 何时使用本 skill
| 场景 | 用本 skill | 不用本 skill |
|---|---|---|
| RAG 知识库构建,需"撒网"式广召回 | ✅ | |
| 同时要 PubMed + 预印本 | ✅ | |
| 只要 PubMed 官方源 + Clinical Queries | ❌ → pubmed-eutils | |
| 拿 DOI 反查全文 OA 链接 | ✅ | |
| 找特定基金(NIH/NSFC/Wellcome)资助的研究 | ✅(grant_id 检索) |
|
| 抽取已知 PMCID 的全文 XML | ❌ → bioc-fulltext-fetch | |
| 临床试验注册号检索 | ❌ → clinical-trials-v2 | |
| 实体(基因/疾病/化合物)关联 | ❌ → pubtator-entity-search |
与 pubmed-eutils 的差异化(必读):
- pubmed-eutils:PubMed 单源、Clinical Queries 过滤、PubDate 精确范围 → 高精准
- europepmc-search:多源聚合 + 自动去重 + 全文链接 + citations metadata → 高召回
- 推荐编排:RAG 知识库构建用本 skill 广召回 → 拿 PMID 列表喂给 pubmed-eutils 做精准复核
2. 前置准备 / 配置加载
Europe PMC RESTful 是完全开放 API,无需 API key,但服务条款要求传 email 联系方式(礼貌请求,便于 EBI 在大流量异常时联系到使用者)。
配置加载顺序(优先级从高到低):
- 项目级:
.config/europepmc.local.yaml(可选,优先于全局) - 用户级:
~/.config/europepmc.yaml - 环境变量:
EUROPEPMC_EMAIL - 都没有 → 退化为
anonymous@example.org并打印 ⚠️ 警告(建议用户配置)
配置文件示例(~/.config/europepmc.yaml):
email: your-email@example.com
default_page_size: 100 # 单页条数,1-1000
default_result_type: core # lite | core | idlist
default_format: json # json | xml | dc
timeout_seconds: 30
max_retries: 3
3. API 端点速查
基础 URL:https://www.ebi.ac.uk/europepmc/webservices/rest/
| 端点 | 用途 | 关键参数 |
|---|---|---|
search |
通用检索(本 skill 主力) | query, resultType, pageSize, cursorMark, format, sort |
article/{source}/{id} |
单篇详情 | source∈{MED,PMC,PPR,AGR,CBA,PAT,CTX,ETH,HIR,NBK} |
{source}/{id}/fullTextXML |
全文 XML(仅 OA) | 仅 PMC 子集 |
{source}/{id}/references |
参考文献 | 分页 |
{source}/{id}/citations |
被引列表 | 分页 |
{source}/{id}/supplementaryFiles |
补充材料 | |
grant/search |
资助检索 | query=GR:"R01..." |
4. 核心检索能力(5 个原子函数)
4.1 search_articles(query, source_filter=None, max_results=200, sort=None)
通用多源检索,自动分页(cursorMark)拉满到 max_results。
query:Europe PMC 查询语法(支持字段限定,见 §5)source_filter:["MED","PMC","PPR"]限定来源;None= 全部sort:"date"(出版日期降序)/"cited"(被引降序)/None(默认相关性)
返回:List[Article],每条含 pmid / pmcid / doi / title / authors / journal / pub_year / abstract / source / is_preprint / preprint_server / has_full_text / oa_status / cited_by_count。
4.2 get_article_details(identifier)
单篇完整元数据。identifier 自动识别:
- 纯数字 → PMID(查 MED 源)
PMC前缀 → PMCID(查 PMC 源)10.开头 → DOI(用 query=DOI:"..."反查)PPR开头 → 预印本 ID(查 PPR 源)
4.3 get_full_text_links(pmid_or_pmcid)
返回所有可用全文链接,按类型分类:
{
"oa_xml": "https://.../fullTextXML", # OA 子集才有
"oa_pdf": "https://europepmc.org/...pdf",
"publisher_html": "https://...",
"subscription": [...], # SUBSCRIPTION 类型
"text_mining": [...], # TM 类型(NLM 等)
"preprint_server": "https://www.biorxiv.org/..."
}
4.4 search_with_grants(query, grant_id=None, funder=None)
资助检索。Europe PMC 有专门的 GRANT_ID / FUNDER 字段。
# 找 NIH R01-CA123456 资助的所有 paper
search_with_grants(query="cancer", grant_id="R01-CA123456")
# 找 Wellcome Trust 资助的全部 cardiology paper
search_with_grants(query="cardiology", funder="Wellcome Trust")
4.5 find_similar_articles(pmid_or_pmcid, limit=20)
调用 Europe PMC 内置的 "Similar Articles" 算法(基于 MeSH + 文本相似度)。比 PubMed elink neighbor 召回略广,适合做 RAG "扩展邻域"。
5. 查询语法核心字段
Europe PMC 查询语法兼容 Lucene 风格,字段大写。常用字段:
| 字段 | 含义 | 示例 |
|---|---|---|
TITLE |
标题 | TITLE:"CAR-T" |
ABSTRACT |
摘要 | ABSTRACT:cytokine |
AUTH |
作者 | AUTH:"Smith J" |
JOURNAL |
期刊 | JOURNAL:"Nature" |
PUB_YEAR |
年份 | PUB_YEAR:[2020 TO 2024] |
PUB_TYPE |
文献类型 | PUB_TYPE:"Review" |
SRC |
来源数据库 | SRC:MED, SRC:PPR, SRC:PMC |
HAS_FT |
有全文 | HAS_FT:Y |
OPEN_ACCESS |
OA | OPEN_ACCESS:Y |
MESH |
MeSH 主题词 | MESH:"Hematologic Neoplasms" |
GRANT_ID |
资助号 | GRANT_ID:"R01CA12345" |
DOI |
DOI | DOI:"10.1038/s41586-020-2196-x" |
LANG |
语种 | LANG:eng |
预印本筛选示例:(SRC:PPR) AND (TITLE:"acute myeloid leukemia") AND (PUB_YEAR:2024)
6. 多源去重逻辑(本 skill 强制内置)
同一篇文章常在 MED + PMC + PPR 同时出现。去重规则按以下优先级合并:
- 第一级:PMID 相同 → 合并,保留 MED 版本(PubMed 元数据最权威)
- 第二级:PMCID 相同 → 合并,保留 PMC 版本(因含全文)
- 第三级:DOI 相同 → 合并,优先 MED > PMC > PPR
- 预印本特殊处理:若同一 DOI 既有预印本(PPR)又有正式发表(MED),两条都保留,但预印本条目标记
superseded_by_pmid: <发表版 PMID>,下游(medical-evidence-grading)据此决定是否丢弃预印本。
返回的合并条目结构:
{
"primary_id": "PMID:38123456",
"all_ids": {"pmid": "38123456", "pmcid": "PMC10987654", "doi": "10.1038/..."},
"sources": ["MED", "PMC"], # 出现的所有源
"is_preprint": False,
"preprint_server": None,
"superseded_by_pmid": None,
...其他元数据
}
7. 预印本处理(医学证据特别注意)
预印本 = source == "PPR"。本 skill 在每条结果中显式标注:
{
"source": "PPR",
"is_preprint": True,
"preprint_server": "bioRxiv", # 或 medRxiv / ChemRxiv / Research Square / SSRN ...
"preprint_doi": "10.1101/2024.03.15.123456",
"posted_date": "2024-03-15",
"version": 2 # 预印本版本号
}
下游约定:medical-evidence-grading skill 看到 is_preprint=True 会自动降权(GRADE 中作为 "very low" 起点),且若同 DOI 已有正式发表版,直接丢弃预印本。本 skill 自身不做证据分级,只如实标注。
8. 分页与流量
- Europe PMC 单页上限:
pageSize=1000 - 分页方式:强制使用
cursorMark(从*起,响应里的nextCursorMark拿来下一页);不要用page=偏移分页(>1000 条时官方明确不保证一致性) - 流量礼貌:全局并发 ≤ 5,每秒 ≤ 8 请求(自动 sleep)
- 429 / 5xx 退避:指数退避
2^n秒,最多重试max_retries(默认 3)
9. 错误处理与边界情况
| 状态 | 处理 |
|---|---|
HTTP 200 + hitCount=0 |
返回空列表 + warning"无命中,建议放宽 query" |
| HTTP 400 | 多半是查询语法错误 → 抛 EuropePMCQueryError,附原始 errMsg |
| HTTP 429 | 指数退避重试 |
| HTTP 5xx | 指数退避重试 |
cursorMark 与上一次相同 |
已到末页,正常终止 |
同 query 已超过 max_results |
截断并返回 truncated=True 标志 |
致命错误一律抛异常,不静默吞(遵循全局 coding-style.md 错误处理原则)。
10. 调用示例
from europepmc_search import EuropePMCClient
cli = EuropePMCClient() # 自动加载 ~/.config/europepmc.yaml
# 1) 广召回:急性髓系白血病近 5 年 PubMed + 预印本
hits = cli.search_articles(
query='(TITLE:"acute myeloid leukemia" OR ABSTRACT:"AML") AND PUB_YEAR:[2020 TO 2025]',
source_filter=["MED", "PPR"],
max_results=500,
sort="date",
)
print(f"去重后 {len(hits)} 条,其中预印本 {sum(h['is_preprint'] for h in hits)} 条")
# 2) DOI 反查全文链接
links = cli.get_full_text_links("10.1056/NEJMoa2024850")
# 3) 找 NIH R01 资助的 CAR-T 研究
ft = cli.search_with_grants(query="CAR-T", grant_id="R01CA255621")
# 4) 邻域扩展
similar = cli.find_similar_articles("38123456", limit=30)
11. 与同体系其他 skill 的协作
[用户问题]
│
├─→ europepmc-search ← 本 skill,广召回 200~1000 条
│ │
│ └─→ pubmed-eutils ← 拿 PMID 子集精准复核 + Clinical Queries 过滤
│ │
│ └─→ bioc-fulltext-fetch ← 对 OA PMC 取全文 XML
│ │
│ └─→ pubtator-entity-search ← 实体识别
│ │
│ └─→ medical-evidence-grading ← GRADE 分级
│ (在此处依据 is_preprint 自动降权)
│
└─→ clinical-trials-v2 / aact-bulk-trials ← 试验注册号另走专线
12. 输出契约(下游 skill 依赖)
每篇文章返回的标准 schema(本 skill 是契约源):
{
"primary_id": "PMID:38123456" | "PMCID:PMC10987654" | "DOI:10.xxx/...",
"all_ids": {"pmid": str|None, "pmcid": str|None, "doi": str|None, "ppr_id": str|None},
"title": str,
"authors": [{"full_name": str, "affiliation": str|None, "orcid": str|None}],
"journal": {"name": str, "iso_abbr": str|None, "issn": str|None},
"pub_year": int,
"pub_date": "YYYY-MM-DD",
"abstract": str|None,
"mesh_terms": [str],
"keywords": [str],
"source": "MED" | "PMC" | "PPR" | "AGR" | "CBA" | "PAT",
"sources_merged": ["MED","PMC"], # 去重前出现的所有源
"is_preprint": bool,
"preprint_server": str|None,
"preprint_doi": str|None,
"version": int|None,
"superseded_by_pmid": str|None,
"has_full_text": bool,
"oa_status": "OA" | "SUBSCRIPTION" | "UNKNOWN",
"full_text_links": {"oa_xml": str|None, "oa_pdf": str|None, "publisher_html": str|None},
"cited_by_count": int,
"grants": [{"grant_id": str, "agency": str, "country": str|None}],
"fetched_at": "ISO-8601 UTC",
"europepmc_url": "https://europepmc.org/article/MED/38123456"
}
下游 skill(medical-evidence-grading / bioc-fulltext-fetch / pubtator-entity-search)按此契约消费,字段缺失用 None,不省略 key。
参考链接
- Europe PMC RESTful Web Service 总览:https://europepmc.org/RestfulWebService
- 查询语法 Help:https://europepmc.org/Help#SSR
- 字段速查:https://europepmc.org/Help#fieldsearch
- 服务条款:https://europepmc.org/About#TermsOfUse
- API 端点:
https://www.ebi.ac.uk/europepmc/webservices/rest/search