clinpgx-database

ClinPGx（PharmGKB）药物基因组学数据库

概述

PharmGKB 于 2024 年更名为 ClinPGx，API 也从 api.pharmgkb.org 迁移到了 api.clinpgx.org。旧主机现在返回 404/405；本文中的所有示例均使用新的端点。我们会结合使用两个互补的 API：

• ClinPGx Data API（api.clinpgx.org/v1）——以记录形式访问基因、药物、变异、临床注释、指南注释、药品标签和通路。响应会将数据封装为 {"data": [...], "status": "success"}。过滤条件使用点分隔的属性路径（例如 relatedChemicals.name=clopidogrel、levelOfEvidence.term=1A）。
• CPIC PostgREST API（api.cpicpgx.org/v1）——以关系形式查询基因型 → 药物推荐记录。使用 PostgREST 过滤语法（column=eq.value；使用 cs.{...} 进行 jsonb 包含查询）。返回扁平的 JSON 数组。

使用 ClinPGx 了解基因、药物或变异的已知信息；使用 CPIC 了解根据表型如何开具处方。模式为 ClinPGx for annotations, CPIC for recommendations。

适用场景

• 获取某个基因-药物组合的 CPIC 基因型特异性剂量建议（例如，CYP2C19 + clopidogrel）——使用 CPIC
• 查询某种药物或某个证据等级的所有药物基因组学临床注释——使用 ClinPGx data/clinicalAnnotation
• 查找某种药物基因的所有 CPIC/DPWG 指南注释——使用 ClinPGx data/guidelineAnnotation
• 将基因符号、药物名称或 rsID 解析为 ClinPGx PA 标识符——使用 data/{gene,drug,variant}
• 跨所有 ClinPGx 记录类型（基因、药物、变异、注释）进行全文搜索——使用 POST /site/search
• 获取 FDA/EMA 药物基因组学药品标签注释——使用 ClinPGx data/label
• 构建结合注释证据与表型特异性建议的精准医疗处方工作流
• 对于生殖系疾病致病性（非 PGx），请使用 clinvar-database
• 对于体细胞癌症药物基因组学，请使用 cosmic-database 或 opentargets-database

先决条件

• Python 包：requests、pandas——标准环境中均已提供
• 数据要求：HGNC 基因符号、小写通用药物名称、dbSNP rsID 或 PA 标识符
• 环境：需要互联网连接；两个主机均无需身份验证
• 速率限制：ClinPGx 主机偶尔会返回 HTTP 429；连续调用之间请插入 time.sleep(0.3–0.5)。CPIC 的限制较宽松。

如果你使用的 pixi/conda 环境已提供 requests 和 pandas，则无需安装——使用 pixi run python ... 调用脚本。

pip install requests pandas

快速入门

import requests

CLINPGX = "https://api.clinpgx.org/v1"
CPIC    = "https://api.cpicpgx.org/v1"

# CPIC genotype → recommendation: clopidogrel + CYP2C19 Poor Metabolizer
drug = requests.get(f"{CPIC}/drug", params={"name": "eq.clopidogrel"}).json()[0]
recs = requests.get(f"{CPIC}/recommendation",
                    params={"drugid": f"eq.{drug['drugid']}",
                            "phenotypes": 'cs.{"CYP2C19":"Poor Metabolizer"}'}).json()
print(f"clopidogrel CYP2C19=PM: {len(recs)} recommendation(s)")
for rec in recs[:2]:
    print(f"  [{rec['classification']}] {rec['drugrecommendation'][:80]}…")

# ClinPGx side: how many CPIC guideline annotations cover CYP2C19?
glines = requests.get(f"{CLINPGX}/data/guidelineAnnotation",
                      params={"relatedGenes.symbol": "CYP2C19",
                              "source": "CPIC", "view": "base"}).json()["data"]
print(f"CYP2C19 CPIC guidelines: {len(glines)}")

核心 API

模块 1：站点全文搜索

当你不知道 PA ID 时，POST /site/search 并使用 JSON 请求体 {"query": "<term>"} 是标准入口。它可以一次性搜索药物、基因、变异、临床注释、指南注释和药品标签。

import requests

CLINPGX = "https://api.clinpgx.org/v1"

r = requests.post(f"{CLINPGX}/site/search",
                  json={"query": "rs4149056"}, timeout=15)
r.raise_for_status()
hits = r.json()["data"]["hits"]
print(f"Total hits: {r.json()['data']['total']}")
for h in hits[:5]:
    print(f"  id={h.get('id')}  name={h.get('name')[:80]}")

# Broader concept search
r = requests.post(f"{CLINPGX}/site/search",
                  json={"query": "TPMT azathioprine"}, timeout=15)
hits = r.json()["data"]["hits"]
print(f"TPMT+azathioprine hits: {len(hits)}")
for h in hits[:5]:
    print(f"  {h.get('id'):>15}  {h.get('name','')[:80]}")

模块 2：基因、药物和变异记录查询

/data/{type} 端点接受简单的属性过滤条件。所有端点均返回 {"data": [...], "status": "success"}——摘要信息使用 view=base，完整嵌套对象使用 view=max。

import requests

CLINPGX = "https://api.clinpgx.org/v1"

# Gene by HGNC symbol
gene = requests.get(f"{CLINPGX}/data/gene",
                    params={"symbol": "CYP2D6", "view": "base"}).json()["data"][0]
print(f"{gene['symbol']}  id={gene['id']}  {gene['name']}")

# Drug by name (lowercase generic preferred)
drug = requests.get(f"{CLINPGX}/data/drug",
                    params={"name": "warfarin", "view": "base"}).json()["data"][0]
print(f"{drug['name']}  id={drug['id']}")

# Variant by rsID
var = requests.get(f"{CLINPGX}/data/variant",
                   params={"name": "rs4149056", "view": "base"}).json()["data"][0]
print(f"{var['name']}  id={var['id']}  significance={var.get('clinicalSignificance')}")

# Direct record fetch when you already have a PA ID
r = requests.get(f"{CLINPGX}/data/drug/PA449088", params={"view": "max"}).json()
d = r["data"]
print(f"PA449088 → {d['name']}  (objCls={d['objCls']})")

模块 3：临床注释

data/clinicalAnnotation 记录将一个变异（location）与一种或多种药物（relatedChemicals）及一个证据等级（levelOfEvidence.term）关联起来。支持的两个过滤条件是 relatedChemicals.name= 和 levelOfEvidence.term=。此端点的 gene= 过滤条件无法正常使用——基因驱动的查询方式请参见模块 4。

import requests, pandas as pd

CLINPGX = "https://api.clinpgx.org/v1"

# All clinical annotations for clopidogrel
data = requests.get(f"{CLINPGX}/data/clinicalAnnotation",
                    params={"relatedChemicals.name": "clopidogrel",
                            "view": "base"}).json()["data"]
print(f"clopidogrel annotations: {len(data)}")

rows = []
for ann in data[:10]:
    loc = ann.get("location") or {}
    drugs = ", ".join(c.get("name", "") for c in ann.get("relatedChemicals", []))
    rows.append({
        "id": ann["id"],
        "variant": loc.get("displayName"),
        "gene": (loc.get("genes") or [{}])[0].get("symbol"),
        "drug": drugs,
        "level": (ann.get("levelOfEvidence") or {}).get("term"),
        "score": ann.get("score"),
    })
print(pd.DataFrame(rows).to_string(index=False))

# All Level 1A clinical annotations (highest evidence)
data = requests.get(f"{CLINPGX}/data/clinicalAnnotation",
                    params={"levelOfEvidence.term": "1A",
                            "view": "base"}).json()["data"]
print(f"Level 1A annotations: {len(data)}")

drug_to_count = {}
for ann in data:
    for c in ann.get("relatedChemicals") or []:
        drug_to_count[c["name"]] = drug_to_count.get(c["name"], 0) + 1
top = sorted(drug_to_count.items(), key=lambda x: -x[1])[:10]
for d, n in top:
    print(f"  {n:3}  {d}")

模块 4：指南注释（基因驱动的查询方式）

data/guidelineAnnotation 支持 relatedGenes.symbol= 和 relatedChemicals.name=，以及 source=（CPIC、DPWG、CPNDS、RNPGx）。这是获取基因→指南覆盖信息的标准方式。

import requests

CLINPGX = "https://api.clinpgx.org/v1"

# All CPIC guidelines mentioning CYP2C19
data = requests.get(f"{CLINPGX}/data/guidelineAnnotation",
                    params={"relatedGenes.symbol": "CYP2C19",
                            "source": "CPIC",
                            "view": "base"}).json()["data"]
print(f"CYP2C19 CPIC guidelines: {len(data)}")
for g in data[:5]:
    print(f"  PA{g['id']}: {g['name'][:80]}")

# Guidelines for a specific drug across all bodies (CPIC, DPWG, …)
data = requests.get(f"{CLINPGX}/data/guidelineAnnotation",
                    params={"relatedChemicals.name": "clopidogrel",
                            "view": "base"}).json()["data"]
by_source = {}
for g in data:
    for s in (g.get("crossReferences") or []):
        by_source.setdefault(s.get("resource", "?"), 0)
        by_source[s["resource"]] = by_source.get(s["resource"], 0) + 1
print(f"clopidogrel guidelines: {len(data)} ({list({g.get('source') for g in data})})")

模块 5：监管药品标签（FDA / EMA）

data/label 记录是 PharmGKB 整理的 FDA/EMA 药物基因组学标签注释。可通过 relatedChemicals.name= 和 source=（FDA、EMA、HCSC、PMDA、Swissmedic）进行筛选。

import requests, pandas as pd

CLINPGX = "https://api.clinpgx.org/v1"

data = requests.get(f"{CLINPGX}/data/label",
                    params={"relatedChemicals.name": "warfarin",
                            "source": "FDA",
                            "view": "base"}).json()["data"]
print(f"warfarin FDA labels: {len(data)}")

rows = [{
    "name": d["name"][:60],
    "biomarker_status": d.get("biomarkerStatus"),
    "testing_required": d.get("testingRequired"),
    "alternate_drug": d.get("alternateDrugAvailable"),
} for d in data]
print(pd.DataFrame(rows).to_string(index=False))

模块 6：CPIC 基因型 → 建议查询链

CPIC 的 PostgREST API 使用 column=eq.value 进行相等匹配，使用 column=cs.{...} 进行 JSONB 包含匹配。标准查询链为 drug → drugid → recommendation，还可选择按表型筛选。

import requests

CPIC = "https://api.cpicpgx.org/v1"

# Resolve drug name to drugid (RxNorm-prefixed)
drug = requests.get(f"{CPIC}/drug",
                    params={"name": "eq.clopidogrel"}).json()[0]
print(f"clopidogrel drugid: {drug['drugid']}")

# All phenotype-specific recommendations for clopidogrel
recs = requests.get(f"{CPIC}/recommendation",
                    params={"drugid": f"eq.{drug['drugid']}"}).json()
print(f"Total recommendations: {len(recs)}")
for rec in recs[:3]:
    print(f"  {rec['phenotypes']}  [{rec['classification']}]")
    print(f"    {rec['drugrecommendation'][:90]}…")

# Phenotype filter via jsonb containment (cs.{...})
# The phenotypes column is a jsonb dict; cs. checks that the query is a subset.
recs = requests.get(f"{CPIC}/recommendation",
                    params={"drugid": f"eq.{drug['drugid']}",
                            "phenotypes": 'cs.{"CYP2C19":"Poor Metabolizer"}'}
                    ).json()
for rec in recs:
    print(f"  [{rec['classification']}] {rec['drugrecommendation'][:90]}…")

# Gene-driven: list every drug with a CPIC pair for CYP2C19
pairs = requests.get(f"{CPIC}/pair",
                     params={"genesymbol": "eq.CYP2C19"}).json()
print(f"\nCYP2C19 CPIC pairs: {len(pairs)}")
drug_ids = sorted({p["drugid"] for p in pairs})
print(f"Sample drug IDs: {drug_ids[:5]}")

核心概念

双主机架构

问题	使用	原因
该药物有哪些临床注释？	ClinPGx data/clinicalAnnotation	注释级证据，附有整理后的 levelOfEvidence.term
哪些 CPIC 指南涵盖该基因？	ClinPGx data/guidelineAnnotation	按 relatedGenes.symbol 筛选；clinicalAnnotation 不支持可用的 gene= 筛选条件
给定表型 X，我应该开具什么处方？	CPIC recommendation + phenotypes	结构化的基因型→行动记录；CPIC 是处方规则的权威来源
哪些 FDA 标签提到了该药物和基因？	ClinPGx data/label?source=FDA	整理后的监管药物基因组学标签
自由文本“有关 X 的任何信息”	ClinPGx POST /site/search	跨记录类型搜索

PharmGKB / ClinPGx 证据等级

证据质量从高到低依次为 1A → 4：

• 1A — 临床指南或 FDA 标签中对变异–药物对的注释（最强）
• 1B — 多项研究重复验证的显著关联
• 2A — 已知药物基因组学基因中的变异，且存在显著关联
• 2B — 中等证据，通常来自单项研究
• 3 — 有限证据（单项研究或未经重复验证）
• 4 — 仅有病例报告 / 生物学合理性

通过 data/clinicalAnnotation 中的 levelOfEvidence.term 筛选。该 term 是一个字符串，而不是枚举值（"1A"，而非 1A）。

ClinPGx 响应封装和视图模式

每个 ClinPGx /data/... 响应的格式均为 {"data": [...] | {...}, "status": "success" | "fail"}。失败时，响应正文为 {"status": "fail", "data": {"errors": [{"message": "..."}]}} — 始终读取这两个键。

• view=base（默认）— 扁平摘要记录；建议用于批量筛选
• view=max — 完整的嵌套对象（relatedDiseases、allelePhenotypes、scoreDetails 等）。数据量更大、速度更慢；仅用于查看单条记录的详细信息。

常见工作流

工作流 1：药物基因面板的 CPIC 覆盖情况

目标： 给定患者的药物基因面板，统计每个基因对应多少条 CPIC 指南注释。

import requests, pandas as pd, time

CLINPGX = "https://api.clinpgx.org/v1"
pharmacogenes = ["CYP2D6", "CYP2C19", "CYP2C9", "DPYD", "TPMT", "SLCO1B1"]

rows = []
for g in pharmacogenes:
    data = requests.get(f"{CLINPGX}/data/guidelineAnnotation",
                        params={"relatedGenes.symbol": g,
                                "source": "CPIC", "view": "base"},
                        timeout=20).json()["data"]
    drugs = sorted({c["name"] for guideline in data
                                for c in (guideline.get("relatedChemicals") or [])})
    rows.append({"gene": g, "cpic_guidelines": len(data),
                 "n_drugs": len(drugs), "sample": ", ".join(drugs[:3])})
    time.sleep(0.3)

df = pd.DataFrame(rows).sort_values("cpic_guidelines", ascending=False)
print(df.to_string(index=False))
df.to_csv("pharmacogene_cpic_coverage.csv", index=False)

工作流 2：药物面板 — CPIC 处方规则查询

目标： 给定处方药物列表，找出哪些药物有针对特定基因型的 CPIC 建议，并列出规则记录。

import requests, pandas as pd, time

CPIC = "https://api.cpicpgx.org/v1"
drugs = ["warfarin", "clopidogrel", "codeine", "simvastatin",
         "metoprolol", "omeprazole", "azathioprine", "tacrolimus"]

rows = []
for name in drugs:
    drug = requests.get(f"{CPIC}/drug", params={"name": f"eq.{name}"}, timeout=15).json()
    if not drug:
        rows.append({"drug": name, "in_cpic": False, "n_recs": 0, "phenotypes": ""}); continue
    did = drug[0]["drugid"]
    recs = requests.get(f"{CPIC}/recommendation",
                        params={"drugid": f"eq.{did}"}, timeout=15).json()
    phens = sorted({f"{k}={v}" for rec in recs
                                  for k, v in (rec.get("phenotypes") or {}).items()})
    rows.append({"drug": name, "in_cpic": True, "n_recs": len(recs),
                 "phenotypes": "; ".join(phens[:3])})
    time.sleep(0.3)

df = pd.DataFrame(rows).sort_values(["in_cpic", "n_recs"], ascending=[False, False])
print(df.to_string(index=False))

工作流 3：变异 → 药物相互作用（由 rsID 驱动）

目标： 从单个 rsID（例如，SLCO1B1 *5 = rs4149056）开始，找出涉及该变异的所有临床注释。

Data API 不接受 rsID 作为筛选属性。使用 POST /site/search 查找相关注释 ID，然后按 ID 获取每条注释。

import requests

CLINPGX = "https://api.clinpgx.org/v1"
rsid = "rs4149056"

hits = requests.post(f"{CLINPGX}/site/search",
                     json={"query": rsid}, timeout=15).json()["data"]["hits"]
print(f"{rsid}: {len(hits)} hits")

# Filter hits that look like clinical annotations
ann_hits = [h for h in hits if h.get("name", "").lower().startswith("clinical annotation")]
print(f"Clinical-annotation hits: {len(ann_hits)}")
for h in ann_hits[:5]:
    print(f"  id={h['id']}  {h['name'][:90]}")

# Dereference one annotation by ID for full detail
if ann_hits:
    ann = requests.get(f"{CLINPGX}/data/clinicalAnnotation/{ann_hits[0]['id']}",
                       params={"view": "max"}, timeout=15).json()["data"]
    drugs = ", ".join(c["name"] for c in (ann.get("relatedChemicals") or []))
    print(f"\nFirst annotation:")
    print(f"  drugs: {drugs}")
    print(f"  level: {(ann.get('levelOfEvidence') or {}).get('term')}")

关键参数

参数	模块 / 端点	默认值	范围 / 选项	作用
view	所有 /data/...	base	base、min、max	字段详细程度；max 包含所有嵌套数组（速度较慢，但内容完整）
relatedChemicals.name	clinicalAnnotation、variantAnnotation、guidelineAnnotation、label、pathway	—	小写通用药名	筛选与某种药物相关的记录
relatedGenes.symbol	guidelineAnnotation、pathway	—	HGNC 基因符号	筛选与某个基因相关的记录（clinicalAnnotation 不支持此参数）
levelOfEvidence.term	clinicalAnnotation	—	"1A"、"1B"、"2A"、"2B"、"3"、"4"	最低证据等级
source	guidelineAnnotation、label	—	CPIC、DPWG、FDA、EMA、HCSC、PMDA、Swissmedic	发布机构
symbol	data/gene	—	HGNC 基因符号	查询基因记录
name	data/drug、data/variant	—	药物名称或 rsID	按规范名称查询记录
CPIC column=eq.value	所有 api.cpicpgx.org/v1/...	—	PostgREST 等值筛选	按精确匹配筛选
CPIC phenotypes=cs.{json}	recommendation	—	JSON 编码的 jsonb 子集	按表型包含关系筛选（如含特殊字符，必须进行 URL 编码）

最佳实践

1. 只解析一次 PA 标识符。 切勿手动构造 ClinPGx PA ID。调用一次 data/{type}?{symbol|name}=...（或 site/search），并缓存返回的 id 以供重复使用——CYP2D6 对应 gene/PA128，氯吡格雷对应 drug/PA449088，rs4149056 对应 variant/PA166154579。

2. 根据问题选择合适的主机。 对于“注释了什么”，使用 ClinPGx；对于“应该开具什么处方”，使用 CPIC。仅从 ClinPGx 推导基因型特异性建议，会遗漏结构化的 recommendation.phenotypes 行。

3. 构建临床工作流时，预先按证据等级筛选。 levelOfEvidence.term=1A 会返回 ClinPGx 中 312 条可操作注释；Level 3/4 记录仅供探索，不应作为处方依据。

4. 不要按基因筛选 clinicalAnnotation，而要通过 relatedGenes.symbol 筛选 guidelineAnnotation。 clinicalAnnotation 端点没有可用的基因属性，任何此类尝试都会返回 HTTP 400。

5. 批量筛选使用 view=base，单条记录深入查询使用 view=max。 列表查询使用 view=max 可能超时或触发 429；两者的负载大小大约相差 5–10 倍。

6. 限制对 ClinPGx 主机的请求频率。 在循环中的顺序查询之间插入 time.sleep(0.3)；连续快速请求时，API 偶尔会返回 HTTP 429。CPIC 可以容忍更快的迭代。

7. 当表型值包含空格或特殊字符时，对 cs.{...} jsonb 筛选器进行 URL 编码。 requests.get(..., params={"phenotypes": 'cs.{"CYP2C19":"Poor Metabolizer"}'}) 可正常工作，因为 requests 会进行编码；手动拼接 URL 字符串则需要使用 urllib.parse.quote。

常用示例

示例 1 — 通过 site/search 进行自由文本发现

适用场景：你有任意字符串（rsID、药物名称、基因、等位基因），想查找相关的 ClinPGx 记录，但不知道该调用哪个端点。

import requests
r = requests.post("https://api.clinpgx.org/v1/site/search",
                  json={"query": "VKORC1 warfarin"}, timeout=15)
hits = r.json()["data"]["hits"]
for h in hits[:10]:
    print(f"  {h.get('id'):>15}  {h.get('name','')[:80]}")

示例 2 — 按 Level 1A 注释数量排列的热门药物

适用场景：构建可操作性最强的 PGx 药物排行榜。

import requests, pandas as pd
data = requests.get("https://api.clinpgx.org/v1/data/clinicalAnnotation",
                    params={"levelOfEvidence.term": "1A", "view": "base"},
                    timeout=30).json()["data"]
counts = {}
for ann in data:
    for c in ann.get("relatedChemicals") or []:
        counts[c["name"]] = counts.get(c["name"], 0) + 1
df = pd.DataFrame(sorted(counts.items(), key=lambda x: -x[1]),
                  columns=["drug", "n_1A_annotations"]).head(15)
print(df.to_string(index=False))

示例 3 — 患者基因型 → 药物建议

适用场景：根据 PGx 检测得出的表型判定，展示所有 CPIC 建议行。

import requests
CPIC = "https://api.cpicpgx.org/v1"

genotype = {"CYP2C19": "Poor Metabolizer"}
drug = "clopidogrel"

did = requests.get(f"{CPIC}/drug", params={"name": f"eq.{drug}"}).json()[0]["drugid"]
import json
recs = requests.get(f"{CPIC}/recommendation",
                    params={"drugid": f"eq.{did}",
                            "phenotypes": f"cs.{json.dumps(genotype)}"}).json()
for rec in recs:
    print(f"[{rec['classification']}] {rec['drugrecommendation']}")
    print(f"  implications: {rec['implications']}")

示例 4 — 带重试机制的可靠会话

适用场景：对大量基因、药物或变异进行长时间循环查询。

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

s = requests.Session()
s.headers.update({"Accept": "application/json"})
s.mount("https://", HTTPAdapter(max_retries=Retry(
    total=4, backoff_factor=1.0,
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET", "POST"])))

r = s.get("https://api.clinpgx.org/v1/data/gene",
          params={"symbol": "CYP2D6", "view": "base"}, timeout=20)
r.raise_for_status()
print(r.json()["data"][0]["name"])

故障排除

问题	原因	解决方案
https://api.pharmgkb.org/v1/... 返回 HTTP 404/405	旧版 PharmGKB 主机已停用；该服务于 2024 年更名为 ClinPGx	迁移到 https://api.clinpgx.org/v1/...。旧版 /clinicalAnnotation?gene=X 现已变为 data/clinicalAnnotation，且筛选条件不同。
{"status":"fail","data":{"errors":[{"message":"No such property: 'gene'"}]}}	data/clinicalAnnotation 不接受 gene= 或 relatedGenes.symbol=	按基因查询时使用 data/guidelineAnnotation?relatedGenes.symbol=X，按药物查询时使用 ?relatedChemicals.name=Y。
{"status":"fail","data":{"errors":[{"message":"Missing criteria."}]}}	data/{type} 列表查询缺少筛选条件和 ID	至少添加一个筛选条件（name=、symbol=、relatedChemicals.name= 等），或通过 ID 使用 data/{type}/{paId} 获取。
GET /site/search?query=... 返回 HTTP 405	site/search 只接受带 JSON 请求体的 POST 请求	使用 requests.post(url, json={"query": "..."})。
循环执行到一半时返回 HTTP 429	触发了 ClinPGx 速率限制	在调用之间插入 time.sleep(0.3–0.5)；使用示例 4 中的 Retry 会话。
https://api.cpicpgx.org/v1/recommendation?phenotypes=cs.{...} 返回 HTTP 400	cs. JSON 未进行 URL 编码	通过 requests 传入 params={"phenotypes": 'cs.{"CYP2C19":"Poor Metabolizer"}'}（自动编码），或手动使用 urllib.parse.quote。
对于明显真实存在的药物，data 列表为空	药物名称不匹配（品牌名与通用名不同；大小写问题）	尝试使用小写通用名；若仍无结果，则使用 POST /site/search 扩展搜索并查找规范 PA ID。
data/variant?name=rs... 返回 1 条记录，但 data/clinicalAnnotation?location.name=rs... 返回 404	rsID 存储在 location.displayName/location.rsid 中，并未作为可筛选属性公开	使用 site/search 根据 rsID 查找注释 ID，然后通过 data/clinicalAnnotation/{id} 逐个获取。（工作流 3。）

相关技能

• clinvar-database — PharmGKB 中发现的变异的生殖系致病性／临床意义（可互补；ClinVar 以疾病为重点，ClinPGx 以药物反应为重点）
• opentargets-database — 与 ClinPGx 药物基因靶点重叠的药物－靶点关联和安全性信号
• chembl-database-bioactivity — ClinPGx 注释药物的生物活性和结合数据
• cosmic-database — 体细胞癌症突变和肿瘤特异性 PGx（与此处介绍的生殖系 PGx 相互补充）

参考资料

• ClinPGx（原 PharmGKB）网站 — 数据库前端；网页链接符合 data/{type}/{paId} URL 格式
• ClinPGx REST API 文档 — 官方端点参考，涵盖 data/... 和 site/search 架构
• CPIC API 文档 — PostgREST 配套 API 的 Swagger UI
• CPIC 指南 — recommendation 行的数据来源；基因型与处方对应关系的权威依据
• Relling 与 Klein（2011），《Nature Reviews Drug Discovery》—— PharmGKB 基础论文
• Whirl-Carrillo 等人（2021），《Clin Pharmacol Ther》—— PharmGKB 数据架构更新