skillhub-003-ensembl-database/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 一行命令提取特定字段。