/references/ensembl_rest_api_reference.md

# Ensembl REST API 参考文档

本文档提供 Ensembl REST API（`https://rest.ensembl.org`）的简明参考。当 `ensembl_api.py` 脚本无法覆盖特定用例时，可用此文档构建自定义查询。

## 通用约定

- **基础 URL：** `https://rest.ensembl.org`（GRCh38）。GRCh37 请使用：`https://grch37.rest.ensembl.org`
- **内容协商：** 设置 `Content-Type` 请求头来控制响应格式：
    - `application/json` — 结构化 JSON（大部分端点的默认格式）
    - `text/plain` — 原始序列字符串
    - `text/x-fasta` — FASTA 格式的序列
    - `text/x-gff3` — GFF3 注释输出
- **速率限制：** 最大 15 次请求/秒。收到 HTTP 429 时，请遵守 `Retry-After` 响应头。
- **区域格式：** `CHR:START..END:STRAND`，其中 STRAND 为 `1`（正向）或 `-1`（反向）。大多数端点也支持连字符格式（`START-END`）。
- **查询参数分隔符：** Ensembl 使用 `;`（分号）分隔查询参数，例如 `?expand=1;mane=1`。标准的 `&` 同样适用。

---

## 查询端点

### `GET /lookup/id/{id}`
查询任意 Ensembl 稳定 ID（基因、转录本、蛋白质）并获取元数据。

- **`expand`**（0/1）：包含子对象（基因的 Transcript 数组，转录本的 Exon 数组，编码转录本的 Translation）
- **`mane`**（0/1）：在转录本上包含 MANE Select/Plus Clinical 注释
- **`db_type`**（字符串）：数据库（默认：`core`）。可选值：`core`、`otherfeatures`
- **`format`**（字符串）：`full`（默认）或 `condensed`
- **`species`**（字符串）：当 ID 不明确时覆盖物种信息

**关键响应字段（基因）：**
`id`、`display_name`（符号）、`biotype`、`description`、`seq_region_name`（染色体）、`start`、`end`、`strand`、`assembly_name`、`Transcript[]`（展开后）。

**关键响应字段（转录本，展开后）：**
`id`、`biotype`、`display_name`、`is_canonical`（0 或 1）、`length`、`MANE[]`（包含 `type` 的数组，值为 `MANE_Select` 或 `MANE_Plus_Clinical`）、`TSL`（Transcript Support Level 对象，含 `value`）、`Exon[]`、`Translation`（含 `id`、`start`、`end`、`length`）。

### `GET /lookup/symbol/{species}/{symbol}`
将基因符号解析为其 Ensembl 稳定 ID。

- **`expand`**（0/1）：包含子对象

返回与 `/lookup/id/` 相同的结构。

### `POST /lookup/id`
批量查询：以 JSON 体形式发送 `{"ids": ["ENSG...", "ENST..."]}`。返回以 ID 为键的字典。

---

## 交叉引用端点

### `GET /xrefs/id/{id}`
获取 Ensembl ID 的外部数据库引用。

- **`external_db`**（字符串）：按数据库名称过滤（例如 `UniProt`、`HGNC`、`RefSeq_mRNA`、`UCSC`、`EntrezGene`）
- **`all_levels`**（0/1）：包含来自父/子特征的交叉引用

**响应：** 对象数组，包含 `primary_id`、`display_id`、`db_display_name`、`dbname`、`description`、`info_type`。

### `GET /xrefs/symbol/{species}/{symbol}`
查找与外部符号匹配的 Ensembl ID。

### `GET /xrefs/name/{species}/{name}`
更广泛的搜索——跨所有外部数据库查询任意名称。

---

## 序列端点

### `GET /sequence/id/{id}`
通过稳定 ID 获取 Ensembl 特征的序列。

- **`type`**（字符串）：`genomic`（默认）、`cdna`、`cds`、`protein`
- **`expand_5prime`**（整数）：向上游延伸 N 个碱基
- **`expand_3prime`**（整数）：向下游延伸 N 个碱基
- **`mask`**（字符串）：屏蔽方式：`hard` 或 `soft`

设置 `Accept: text/x-fasta` 获取 FASTA 格式输出，`text/plain` 获取原始字符串。

### `GET /sequence/region/{species}/{region}`
获取坐标窗口内的基因组 DNA。

- **`coord_system_version`**（字符串）：组装版本（例如 `GRCh38`）
- **`expand_5prime`**（整数）：向上游延伸 N 个碱基
- **`expand_3prime`**（整数）：向下游延伸 N 个碱基
- **`mask`**（字符串）：`hard` 或 `soft` 重复序列屏蔽
- **`mask_feature`**（0/1）：应用特征级屏蔽

区域格式：`CHR:START..END:STRAND`（例如 `X:1000000..1000100:1`）。

### `POST /sequence/region/{species}`
批量：发送 `{"regions": ["X:1000..2000", "7:100..200"]}`。

---

## 重叠端点

### `GET /overlap/region/{species}/{region}`
查找与基因组区域重叠的特征。适用于查找某基因座的基因、窗口内的变异或调控特征。

- **`feature`**（字符串）：要返回的特征类型。可重复使用以指定多个类型。可选值：`gene`、`transcript`、`cds`、`exon`、`repeat`、`simple`、`misc`、`variation`、`somatic_variation`、`structural_variation`、`somatic_structural_variation`、`constrained`、`regulatory`、`motif`、`chipseq`、`array_probe`
- **`biotype`**（字符串）：按生物类型过滤（例如 `protein_coding`）
- **`variant_set`**（字符串）：用于变异过滤的短集合名称

**示例：** 查找区域内所有基因和转录本：
```
/overlap/region/human/7:140424943-140624564?feature=gene;feature=transcript
```

### `GET /overlap/id/{id}`
与 Ensembl 特征（基因、转录本等）重叠的特征。`feature` 参数选项同上。

### `GET /overlap/translation/{id}`
与翻译产物重叠的蛋白质特征。用于结构域注释。

- **`feature`**（字符串）：`protein_feature`、`residue_overlap`、`translation_exon`
- **`type`**（字符串）：按源数据库名称过滤（例如 `Pfam`、`Gene3D`、`CDD`、`Smart`、`SuperFamily`、`PANTHER`、`Prosite_patterns`、`PRINTS`、`MobiDBLite`）

**示例：** 获取某个蛋白质的 Pfam 结构域注释：
```
/overlap/translation/ENSP00000269305?feature=protein_feature;type=Pfam
```

**响应字段（protein_feature）：** `type`（源数据库）、`id`（结构域登录号）、`description`、`start`（氨基酸起始位置）、`end`。

---

## 比较基因组学端点

### `GET /homology/id/{species}/{id}`
获取某个基因的同源物（直系同源/旁系同源）。

- **`type`**（字符串）：`orthologues`、`paralogues`、`projections`、`all`
- **`target_species`**（字符串）：限定到特定目标物种
- **`target_taxon`**（整数）：按 NCBI 分类单元 ID 限定
- **`sequence`**（字符串）：`none`、`cdna`、`protein` — 包含比对后的序列

### `GET /homology/symbol/{species}/{symbol}`
同上，但按基因符号而非 ID 查询。

### `GET /genetree/id/{id}`
通过 Ensembl Compara 树 ID 获取完整的基因树。

### `GET /genetree/member/id/{species}/{id}`
获取包含特定基因的基因树。

---

## 变异端点

### `GET /variation/{species}/{id}`
获取已知变异（通过 rsID 或 Ensembl 变异 ID）的详细信息。

**响应字段：** `name`（rsID）、`mappings[]`（包含 `location`、`allele_string`、`start`、`end`、`strand`）、`ancestral_allele`、`minor_allele`、`MAF`、`clinical_significance[]`、`source`。

### `GET /variant_recoder/{species}/{id}`
在不同格式（HGVS、VCF、SPDI、rsID）之间转换变异表示。

**响应字段：** `spdi[]`、`hgvsg[]`、`hgvsc[]`、`hgvsp[]`、`vcf_string[]`、`id[]`（rsID）。

---

## VEP（变异效应预测器）端点

### `GET /vep/{species}/region/{region}/{allele}`
预测基因组变异的影响。

区域格式：`CHR:START-END:STRAND`（例如 `9:21971147-21971147:1`）。Allele 为替代等位基因字符串。

### `GET /vep/{species}/id/{id}`
通过 rsID 预测变异影响。

### `GET /vep/{species}/hgvs/{hgvs_notation}`
通过 HGVS 命名法预测变异影响。

**插件参数（以查询参数形式附加）：**

- `AlphaMissense=1` — AlphaMissense 致病性预测
- `Conservation=1` — PhyloP 保守性评分
- `DosageSensitivity=1` — 单倍剂量不足/三倍剂量敏感
- `LoF=loftee` — LOFTEE 功能缺失评估
- `LOEUF=1` — 功能缺失观察值与期望值上限比值
- `NMD=1` — 无义介导的 mRNA 降解预测
- `UTRAnnotator=1` — 5'/3' UTR 变异注释
- `mutfunc=1` — 功能影响预测
- `IntAct=1` — 蛋白质相互作用影响
- `MaveDB=1` — 多重分析评分
- `OpenTargets=1` — Open Targets 遗传学数据

**关键响应字段：** `most_severe_consequence`、`transcript_consequences[]`（包含 `gene_symbol`、`transcript_id`、`consequence_terms[]`、`amino_acids`、`sift_prediction`、`sift_score`、`polyphen_prediction`、`polyphen_score`、`am_class`、`am_pathogenicity`、`conservation`、`lof`、`loeuf`）。

### `POST /vep/{species}/region`
批量 VEP：以类似 VCF 的格式发送 `{"variants": ["1 100 . A T . . ."]}`。

---

## 映射端点

### `GET /map/{species}/{asm_one}/{region}/{asm_two}`
在不同组装版本之间转换坐标（例如 GRCh37 → GRCh38）。

**示例：**
```
/map/human/GRCh37/17:43044295-43125370/GRCh38
```

**响应：** `mappings[]`，包含 `original` 和 `mapped` 坐标块。

### `GET /map/cdna/{id}/{region}`
将 cDNA 坐标映射到某个转录本的基因组坐标。

### `GET /map/cds/{id}/{region}`
将 CDS 坐标映射到基因组坐标。

### `GET /map/translation/{id}/{region}`
将蛋白质（氨基酸）位置映射到基因组坐标。

---

## 表型端点

### `GET /phenotype/gene/{species}/{gene}`
某个基因（按符号或 Ensembl ID）的表型注释。

### `GET /phenotype/region/{species}/{region}`
某个基因组区域中与表型相关的变异。

### `GET /phenotype/term/{species}/{term}`
查找与某个表型术语（本体论 ID 或描述字符串，例如 `coffee consumption`）相关的变异/基因。

---

## 连锁不平衡端点

### `GET /ld/{species}/{id}/{population_name}`
计算某个变异周围窗口内变异的 LD。

- **`window_size`**（整数）：窗口大小，单位 kb（默认：500）
- **`r2`**（浮点数）：最小 r² 阈值
- **`d_prime`**（浮点数）：最小 D' 阈值

### `GET /ld/{species}/pairwise/{id1}/{id2}`
两个特定变异之间的成对 LD。

### `GET /ld/{species}/region/{region}/{population_name}`
某个区域内所有变异对的 LD。

群体名称：例如 `1000GENOMES:phase_3:CEU`、`1000GENOMES:phase_3:YRI`。

---

## 信息端点

### `GET /info/assembly/{species}`
组装元数据（核型、顶层区域、坐标系统）。

### `GET /info/assembly/{species}/{region_name}`
特定染色体/区域的详细信息（长度、条带）。

### `GET /info/species`
列出 Ensembl REST API 中所有可用的物种。

### `GET /info/external_dbs/{species}`
列出所有可用于交叉引用的外部数据库名称。有助于查找正确的 `external_db` 参数值。

### `GET /info/biotypes/{species}`
列出某个物种的所有生物类型分类。

---

## 自定义查询的最佳实践

1. **始终设置 `Content-Type`**：JSON 响应设为 `application/json`，序列端点设为 `text/plain` 或 `text/x-fasta`。
2. **在查询端点使用 `expand=1`**：通过一次调用获取子特征，避免为每个转录本/外显子分别发起请求。
3. **优先使用批量端点**（`POST /lookup/id`、`POST /sequence/region`）：当查询多个 ID 或区域时，减少 HTTP 往返次数。
4. **使用交叉引用过滤前检查 `info/external_dbs`**：数据库名称字符串区分大小写，且并非总是显而易见（例如 `UniProt_gn` 而非 `UniProt`）。
5. **区域大小限制**：`/overlap/region/` 端点对大多数特征类型有最大 5 Mb 的区域大小限制。较大区域请拆分。
6. **当坐标为 GRCh37（hg19）组装时**，使用 `grch37.rest.ensembl.org` 作为基础 URL。大多数端点在该旧版服务器上支持相同的路径。
7. **将响应保存到临时文件**——不要试图将大型 JSON 响应读入上下文。使用 `jq` 或 Python 一行命令提取特定字段。