clinpgx-database

ClinPGx（PharmGKB）薬理ゲノミクスデータベース

概要

PharmGKBは2024年にClinPGxへリブランドされ、APIはapi.pharmgkb.orgからapi.clinpgx.orgへ移行しました。旧ホストは現在404/405を返します。ここに記載されているすべての例では、新しいエンドポイントを使用します。相互補完的な2つの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、jsonbの包含にはcs.{...}）を使用します。フラットなJSON配列を返します。

遺伝子／薬剤／バリアントについて「何がわかっているか」を調べるにはClinPGxを、表現型に基づいて「どのように処方するか」を調べるにはCPICを使用します。基本的な使い分けはClinPGx for annotations, CPIC for recommendationsです。

使用する場面

• 遺伝子と薬剤の組み合わせ（例：CYP2C19とclopidogrel）に対する、CPICの遺伝子型別投与量の推奨事項を取得する場合 — 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の制限はより緩やかです。

requestsとpandasがすでに用意されているpixi／conda環境を使用している場合、インストールは不要です。スクリプトは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がわからない場合の標準的な入口は、JSON本文{"query": "<term>"}を指定したPOST /site/searchです。薬剤、遺伝子、バリアント、臨床アノテーション、ガイドラインアノテーション、ラベルを一括で検索します。

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）を1つ以上の薬剤（relatedChemicals）およびエビデンスレベル（levelOfEvidence.term）に関連付けます。サポートされているフィルターはrelatedChemicals.name=とlevelOfEvidence.term=の2つです。このエンドポイントでは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 レコードは、FDA／EMA の薬理ゲノミクス関連ラベルについて PharmGKB がキュレーションした注釈です。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、JSONB の包含条件に column=cs.{...} を使用します。標準的な検索チェーンは 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]}")

主な概念

2 つのホストを使うアーキテクチャ

質問	使用するもの	理由
この医薬品にはどのような臨床注釈がありますか？	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	all /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	all 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 件取得できます。レベル 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 — レベル 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 も指定されていません	1 つ以上のフィルター（name=、symbol=、relatedChemicals.name=、…）を追加するか、data/{type}/{paId} で ID を指定して取得してください。
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 データアーキテクチャの更新