Ensembl REST API 基因组检索实战指南：基于 database-lookup Skill 完成基因、序列、变异与同源注释查询

本指南系统讲解 Ensembl REST API（参考文档）在数据库检索场景下的完整用法，覆盖基因 ID/符号解析、序列获取、VEP 变异效应预测、区域特征查询、比较基因组与元数据接口。读完本文后，你可以用浏览器地址栏、curl 或 Agent 的 HTTP 工具，把基因符号、Ensembl ID、HGVS 记法或染色体坐标可复现地转换为结构化注释数据，并掌握版本选择、批量策略与限速规避等工程化细节。

Ensembl 在本仓库的 database-lookup 技能中被收录为“生物学与基因组学”分组的核心数据库：在 数据库选择指南 中，它是“基因组序列、变异、转录本”类问题的首选库，也是基因信息查询中 NCBI Gene 的主要交叉验证库。调用前请先阅读 检索契约与审计清单，明确目标实体、物种/基因组版本与所需字段，再发起请求。

一、选择正确的 Base URL：物种库、Ensembl Genomes 与 GRCh37 归档

Ensembl REST API 通过同一个服务端点提供三类数据访问，区别只在于 URL 主机名：

场景	Base URL	说明
当前主要注释（人类 GRCh38 等）	https://rest.ensembl.org	默认入口，包含全部已发布物种
植物、真菌、细菌、原生生物、后生动物（Ensembl Genomes）	https://rest.ensembl.org	与主库同一端点；Ensembl Genomes 已并入主 REST API，无需单独前缀
GRCh37（hg19）归档	https://grch37.rest.ensembl.org	需要 hg19 旧坐标系时使用，其余参数与主库一致

版本选择直接影响坐标与转录本含义。根据本技能 检索契约 的要求，凡涉及染色体坐标与 HGVS 变异的查询，必须在检索参数中明确“基因组构建 + 转录本版本”，Ensembl 正是在 URL 路径中用 {species} 表达物种、用上面三类 Base URL 区分构建版本的数据库之一。

二、认证与公共请求头

• 无需 API Key：所有端点均公开可访问，无需申请令牌。
• 无鉴权：直接携带参数请求即可。
• 内容协商：REST 服务默认按 Content-Type 头做内容协商。对 GET 请求，统一在 URL 后追加 ?content-type=application/json；对 POST 请求，在请求头设置 Content-Type: application/json。若未声明，默认返回 XML/HTML 格式。

curl 中最稳妥的写法是同时满足“URL 查询参数协商 + 请求头协商”：

curl -s -H 'Accept: application/json' \
  'https://rest.ensembl.org/lookup/symbol/homo_sapiens/TP53?content-type=application/json'

三、基因与特征解析：从符号或稳定 ID 出发

3.1 按基因符号查询（lookup/symbol）

GET /lookup/symbol/{species}/{symbol}?content-type=application/json

参数	类型	描述
species	string	必填。物种名，如 homo_sapiens、mus_musculus
symbol	string	必填。基因符号，如 TP53、BRCA1
expand	int	设为 1 时返回包含转录本、翻译产物、外显子的完整子对象

示例：

https://rest.ensembl.org/lookup/symbol/homo_sapiens/TP53?content-type=application/json
https://rest.ensembl.org/lookup/symbol/homo_sapiens/BRCA1?content-type=application/json;expand=1

返回的核心字段（以 TP53 为例）直接给出了从符号到基因组定位与证据源的全部信息：

{
  "id": "ENSG00000141510",
  "display_name": "TP53",
  "description": "tumor protein p53 [Source:HGNC Symbol;Acc:HGNC:11998]",
  "species": "homo_sapiens",
  "object_type": "Gene",
  "biotype": "protein_coding",
  "assembly_name": "GRCh38",
  "seq_region_name": "17",
  "start": 7661779,
  "end": 7687538,
  "strand": -1,
  "source": "ensembl_havana",
  "logic_name": "ensembl_havana_gene_homo_sapiens",
  "version": 16,
  "Transcript": [...]
}

字段语义速览：id 是权威 Ensembl 稳定 ID；display_name 为 HGNC 符号；biotype 区分 protein_coding 等功能类别；seq_region_name/start/end/strand 给出染色体定位与正负链（此处 TP53 位于 17 号染色体负链）；source 与 logic_name 记录注释来源流水线（ensembl_havana）；expand=1 时 Transcript 数组会携带每条转录本的完整结构。

从本技能的工作流看，/lookup/symbol 是“由基因符号解析到 Ensembl ID 的最快路径”，符号层面的解析经常是该技能 常见标识符格式 中的第一步：Ensembl gene ID 采用 ENSG###########（如 TP53 的 ENSG00000141510）格式，并作为下游 Open Targets、GTEx 等多个库的通用键。

3.2 按稳定 ID 查询任意对象（lookup/id）

GET /lookup/id/{id}?content-type=application/json

参数	类型	描述
id	string	必填。Ensembl 稳定 ID，可为基因、转录本、蛋白或外显子
expand	int	设为 1 时包含子对象（基因会带出转录本等）
db_type	string	数据库类型：core、otherfeatures、cdna、rnaseq

示例（同一 TP53 位点的三种对象层级）：

https://rest.ensembl.org/lookup/id/ENSG00000141510?content-type=application/json;expand=1
https://rest.ensembl.org/lookup/id/ENST00000269305?content-type=application/json
https://rest.ensembl.org/lookup/id/ENSP00000269305?content-type=application/json

3.3 批量解析（POST，单次最多 1000 个 ID）

当需要一次性解析大量 ID 时，务必使用批量端点——它不仅减少往返，还按“单次请求”计入限速额度：

POST /lookup/id
Content-Type: application/json

{ "ids": ["ENSG00000141510", "ENSG00000012048", "ENSG00000157764"] }

响应为“以 ID 为键”的映射，便于程序直接按键取值：

{
  "ENSG00000141510": {
    "id": "ENSG00000141510",
    "display_name": "TP53",
    ...
  },
  "ENSG00000012048": { ... }
}

由于本技能 SKILL.md 明确说明 POST 端点“无法用只支持 GET 的 WebFetch 调用”，需要回退到 curl 等 shell 工具：

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"ids":["ENSG00000141510","ENSG00000012048","ENSG00000157764"]}' \
  'https://rest.ensembl.org/lookup/id?content-type=application/json'

3.4 交叉引用解析（xrefs/id 与 xrefs/symbol）

Ensembl 记录会登记到各外部数据库的映射，可用 Xrefs 端点统一完成标识符桥接：

GET /xrefs/id/{id}?content-type=application/json

示例——解析 TP53 基因的跨库映射：

https://rest.ensembl.org/xrefs/id/ENSG00000141510?content-type=application/json

响应给出每个外部库的主键与显示名，覆盖 HGNC、UniProt、EntrezGene 等：

[
  {
    "primary_id": "11998",
    "display_id": "TP53",
    "dbname": "HGNC",
    "db_display_name": "HGNC Symbol"
  },
  {
    "primary_id": "P04637",
    "display_id": "P53_HUMAN",
    "dbname": "Uniprot/SWISSPROT"
  },
  {
    "primary_id": "7157",
    "display_id": "TP53",
    "dbname": "EntrezGene"
  }
]

同样支持按符号发起：

GET /xrefs/symbol/{species}/{symbol}?content-type=application/json
https://rest.ensembl.org/xrefs/symbol/homo_sapiens/TP53?content-type=application/json

在 SKILL.md 的标识符解析流程中，这正是“基因符号 → Ensembl ID → UniProt/NCBI Gene”转换的标准实现：例如把 TP53 转换为 Ensembl ID 时直接调用 /xrefs/symbol/homo_sapiens/{symbol}；而当某个库不识别当前 ID 时，优先用 Xrefs 把它桥接到目标库的标识体系，而不是在不同 API 间盲目扩散查询。官方参考建议也强调：把 /xrefs/id 与基因 ID 组合，即可向 UniProt、NCBI Gene、HGNC 等库交叉引用。

四、序列获取：按 ID 与按坐标区间

4.1 按稳定 ID 取序列（sequence/id）

GET /sequence/id/{id}?content-type=application/json

参数	类型	描述
id	string	Ensembl 稳定 ID（基因、转录本或蛋白）
type	string	genomic、cdna、cds、protein；默认随对象类型自动变化
format	string	json 或 fasta
expand_3prime	int	向 3′ 端延伸 N 个碱基
expand_5prime	int	向 5′ 端延伸 N 个碱基
mask	string	soft（重复区转为小写）或 hard（重复区以 N 掩盖）

各场景示例：

# 蛋白序列
https://rest.ensembl.org/sequence/id/ENSP00000269305?content-type=application/json

# CDS 序列
https://rest.ensembl.org/sequence/id/ENST00000269305?type=cds&content-type=application/json

# 基因组序列并带侧翼区（5′ 扩 1000 bp、3′ 扩 500 bp）
https://rest.ensembl.org/sequence/id/ENSG00000141510?type=genomic&expand_5prime=1000&expand_3prime=500&content-type=application/json

# FASTA 格式
https://rest.ensembl.org/sequence/id/ENSP00000269305?content-type=text/x-fasta

JSON 响应由 seq 承载实际序列，molecule 标识分子类型，desc 记录坐标来源：

{
  "id": "ENSP00000269305",
  "seq": "MEEPQSDPSVEPPLSQETFSDL...",
  "molecule": "protein",
  "desc": "chromosome:GRCh38:17:7661779:7687538:-1"
}

4.2 按坐标区间取序列（sequence/region）

GET /sequence/region/{species}/{region}?content-type=application/json

区间格式为 chromosome:start..end 或 chromosome:start..end:strand。示例为取 17 号染色体正链 7661779..7662000 的序列：

https://rest.ensembl.org/sequence/region/homo_sapiens/17:7661779..7662000:1?content-type=application/json

实操提示：需要跨基因座侧翼序列（启动子、增强子区域）时，expand_5prime/expand_3prime 比手工拼接坐标更不易出错；需要重复区可见性时配合 mask=soft/hard 使用。这类“带坐标帧约束的序列需求”正对应检索契约中“完整还是局部序列”“哪个 build/转录本版本”等必须提前澄清的字段。

五、变异注释：VEP 与已知变异查询

VEP（Variant Effect Predictor）把一条变异（HGVS、坐标+等位基因、或 rsID）翻译成转录本级后果与致病性打分，是坐标型变异的首选注释端点。

5.1 按 HGVS 记法

GET /vep/{species}/hgvs/{hgvs_notation}?content-type=application/json

示例——转录本编码区 c.817C>T（cDNA 层面 817 位 C→T）与基因组 g.7674220G>A：

https://rest.ensembl.org/vep/homo_sapiens/hgvs/ENST00000269305.9:c.817C>T?content-type=application/json
https://rest.ensembl.org/vep/homo_sapiens/hgvs/17:g.7674220G>A?content-type=application/json

5.2 按基因组坐标与等位基因

GET /vep/{species}/region/{region}/{allele}?content-type=application/json

https://rest.ensembl.org/vep/homo_sapiens/region/17:7674220-7674220:1/A?content-type=application/json

5.3 按 rsID

GET /vep/{species}/id/{rsid}?content-type=application/json

https://rest.ensembl.org/vep/homo_sapiens/id/rs699?content-type=application/json

5.4 理解 VEP 响应

VEP 顶层是数组，每个元素对应一次输入；其中 most_severe_consequence 给出全转录本最严重后果，transcript_consequences 则细化到每条转录本。以下为 17:g.7674220G>A（TP53 第 248 位密码子）的典型响应：

[
  {
    "input": "17:g.7674220G>A",
    "assembly_name": "GRCh38",
    "seq_region_name": "17",
    "start": 7674220,
    "end": 7674220,
    "strand": 1,
    "allele_string": "G/A",
    "most_severe_consequence": "missense_variant",
    "transcript_consequences": [
      {
        "gene_id": "ENSG00000141510",
        "gene_symbol": "TP53",
        "transcript_id": "ENST00000269305",
        "biotype": "protein_coding",
        "consequence_terms": ["missense_variant"],
        "impact": "MODERATE",
        "amino_acids": "R/H",
        "codons": "cGc/cAc",
        "protein_start": 248,
        "polyphen_prediction": "probably_damaging",
        "polyphen_score": 1.0,
        "sift_prediction": "deleterious",
        "sift_score": 0.0,
        "cadd_phred": 35.0
      }
    ],
    "colocated_variants": [
      {
        "id": "rs28934578",
        "frequencies": { ... },
        "clin_sig": ["pathogenic"]
      }
    ]
  }
]

字段解读：allele_string 展示参考/替代等位基因；most_severe_consequence 与逐转录本的 consequence_terms 描述功能后果（此处为错义变异 missense_variant）；impact 为后果严重性分级（此处 MODERATE）；codons/amino_acids 显示密码子 cGc→cAc 导致的氨基酸替换 R/H（精氨酸→组氨酸，位于 protein_start 248 位，对应 TP53 已知热点 R248）；polyphen_prediction/score、sift_prediction/score、cadd_phred 分别给出三种常用功能损伤打分；colocated_variants 把该位点关联到 dbSNP rsID 与临床意义（此处 rs28934578，clin_sig: pathogenic）。

5.5 批量 VEP（POST，单次最多 200 个变异）

POST /vep/homo_sapiens/region
Content-Type: application/json

{ "variants": ["17 7674220 7674220 G/A 1", "7 140753336 140753336 A/T 1"] }

其中每个元素为 VCF 风格的空间分隔串：染色体 起点 终点 参考/替代 链。curl 调用方式：

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"variants":["17 7674220 7674220 G/A 1","7 140753336 140753336 A/T 1"]}' \
  'https://rest.ensembl.org/vep/homo_sapiens/region'

5.6 已知变异信息（variation）

若只是查询某 rsID 的位点、等位基因与群体频率，直接使用 /variation：

GET /variation/{species}/{rsid}?content-type=application/json

https://rest.ensembl.org/variation/homo_sapiens/rs699?content-type=application/json

响应包含 dbSNP 来源说明、所有基因组构建下的 mapping、MAF（次等位基因频率）、minor_allele、clinical_significance、ancestral_allele 与别名：

{
  "name": "rs699",
  "source": "Variants (including SNPs and indels) imported from dbSNP",
  "mappings": [
    {
      "seq_region_name": "1",
      "start": 230710048,
      "end": 230710048,
      "strand": 1,
      "allele_string": "A/G",
      "assembly_name": "GRCh38",
      "location": "1:230710048-230710048"
    }
  ],
  "MAF": 0.35,
  "minor_allele": "G",
  "clinical_significance": [],
  "synonyms": [],
  "ancestral_allele": "A"
}

结合本技能用法：在坐标与 rsID 之间互转时，Ensembl VEP 承担“用坐标获取后果注释与关联 rsID”的角色，而 /variation 承担“rsID → 位点/频率”的反向角色——两者互补，是处理变异类检索契约的标准组合。

六、区域特征：Overlap 查询

需要“某个区间内有哪些注释特征”时使用 Overlap 端点，可用作区间精细扫描与跨注释层叠加。

GET /overlap/region/{species}/{region}?feature={type}&content-type=application/json

参数	类型	描述
region	string	格式 chr:start-end
feature	string	可为 gene、transcript、cds、exon、repeat、simple、misc、variation、somatic_variation、structural_variation、regulatory、motif、chipseq、constrained 之一；该参数可重复以查询多种特征

示例——列出 TP53 所在区间（17:7660000-7690000）的全部基因与全部调控特征：

https://rest.ensembl.org/overlap/region/homo_sapiens/17:7660000-7690000?feature=gene&content-type=application/json
https://rest.ensembl.org/overlap/region/homo_sapiens/17:7660000-7690000?feature=regulatory&content-type=application/json

七、比较基因组学与调控注释

7.1 同源关系（Homology）

GET /homology/id/{id}?content-type=application/json

参数	类型	描述
id	string	Ensembl 基因 ID
type	string	orthologues、paralogues、projections、all
target_species	string	限定目标物种，如 mus_musculus
target_taxon	int	按 NCBI taxon ID 限定
sequence	string	none、cdna、protein；是否附带比对序列

示例——查人类 TP53 的小鼠直系同源基因：

https://rest.ensembl.org/homology/id/ENSG00000141510?type=orthologues&target_species=mus_musculus&content-type=application/json

响应在 data[].homologies[] 中给出同源关系类型与两侧对象；perc_id/perc_pos 衡量蛋白一致度与相似度，dn_ds 反映选择压力：

{
  "data": [
    {
      "id": "ENSG00000141510",
      "homologies": [
        {
          "type": "ortholog_one2one",
          "target": {
            "id": "ENSMUSG00000059552",
            "species": "mus_musculus",
            "protein_id": "ENSMUSP00000073359",
            "perc_id": 77.8,
            "perc_pos": 86.0
          },
          "source": {
            "id": "ENSG00000141510",
            "species": "homo_sapiens",
            "protein_id": "ENSP00000269305"
          },
          "method_link_type": "ENSEMBL_ORTHOLOGUES",
          "dn_ds": 0.15
        }
      ]
    }
  ]
}

同源查询同样支持从符号出发：

GET /homology/symbol/{species}/{symbol}?content-type=application/json
https://rest.ensembl.org/homology/symbol/homo_sapiens/TP53?type=orthologues&target_species=mus_musculus&content-type=application/json

7.2 调控特征（Regulatory）

GET /regulatory/species/{species}/id/{id}?content-type=application/json

https://rest.ensembl.org/regulatory/species/homo_sapiens/id/ENSR00000000163?content-type=application/json

7.3 表型关联（Phenotype）

GET /phenotype/gene/{species}/{gene}?content-type=application/json

https://rest.ensembl.org/phenotype/gene/homo_sapiens/TP53?content-type=application/json

八、物种与组装元数据

8.1 可用物种列表

GET /info/species?content-type=application/json

返回全部可用物种及其组装信息——多物种场景下先在此确认目标物种是否受支持，比盲发请求更高效。

8.2 组装信息

GET /info/assembly/{species}?content-type=application/json

https://rest.ensembl.org/info/assembly/homo_sapiens?content-type=application/json

返回染色体名称与长度、组装名（GRCh38）、坐标系等，可用于坐标范围校验与区间合法性检查。

九、LD（连锁不平衡）查询

GET /ld/{species}/pairwise/{rsid1}/{rsid2}?population_name={pop}&content-type=application/json

示例——在 1000 Genomes CEU 群体中计算 rs699 与 rs4762 的配对 LD：

https://rest.ensembl.org/ld/homo_sapiens/pairwise/rs699/rs4762?population_name=1000GENOMES:phase_3:CEU&content-type=application/json

注意 population_name 值中的冒号与下划线应保持原样并按需做 URL 编码，这与 SKILL.md 中“对特殊字符做 URL 编码（如 HP:0001250 → HP%3A0001250）”的通用安全要求一致。

十、常用物种命名速查

Ensembl 的 {species} 一律使用小写下划线拉丁名，不可用俗称或缩写：

物种	API 名称
人类	homo_sapiens
小鼠	mus_musculus
大鼠	rattus_norvegicus
斑马鱼	danio_rerio
果蝇	drosophila_melanogaster
鸡	gallus_gallus
狗	canis_lupus_familiaris
猪	sus_scrofa

依据检索契约中的“物种显式化”原则，跨物种查询时必须显式传入该字段，不得默认人类——Ensembl 正是把 {species} 放进 URL 路径的典型代表，species 拼错或使用俗称是此类查询最常见失败原因。

十一、速率限制与批量调用策略

• 普通用户（无 API Key）默认 每秒 15 个请求。
• 可选注册 API Key 以获取更高限额。
• 超限请求返回 HTTP 429，并携带 Retry-After 响应头。
• 批量端点（POST）按单次请求计数，应优先用批量端点降低调用总量。
• /lookup/id 批量 POST 上限 1000 个 ID/次；VEP 批量 POST 上限 200 个变异/次。
• 限速状态通过响应头反馈：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。

这与 SKILL.md 的请求纪律相互印证：Ensembl（15 req/s）被列为“必须串行化请求的限速 API”之一；遇到 429/503 时短暂等待后重试一次即可；对于超大规模的全量数据需求，应改用官方 bulk 下载而非逐页爬取。结合检索契约的完整性协议：批量抓取前先估算“总量 × 页大小 ÷ 单批上限”，确保总调用数不超过阈值并逐批记录累计计数。

十二、错误格式与状态码

所有错误统一返回 JSON 错误体：

{
  "error": "ID 'ENSG999' not found"
}

HTTP 状态码	含义
400	请求格式错误
404	目标不存在
429	触发限速
503	服务暂不可用

收到 404 时优先怀疑 ID 格式而非服务故障。可对照 SKILL.md 的通用标识符表核验：如 ENSG00000141510 这类 ENSG 前缀 + 11 位数字才符合 Ensembl 基因 ID 规范；若基因符号查询失败，先尝试把符号经 NCBI Gene 解析为 ID，再用 ID 重查。

十三、Agent 实战要点：把参考文档变成可复现检索

把上述端点组织进一次真实的“检索契约”执行，典型链路如下：

1. 解析：/lookup/symbol/homo_sapiens/TP53 → 拿到 ENSG00000141510 与 GRCh38 坐标；
2. 交叉引用：/xrefs/id/ENSG00000141510 → 得到 UniProt P04637、HGNC 11998、EntrezGene 7157；
3. 序列：/sequence/id/ENSP00000269305?content-type=application/json → 蛋白序列；加 type=cds 取编码序列；
4. 变异：对坐标型变异调 VEP /vep/homo_sapiens/region/17:7674220-7674220:1/A 或批量 POST，得到 most_severe_consequence、Polyphen/SIFT/CADD 打分与关联 rsID；
5. 验证与审计：记录“物种 + build + 端点 + 参数 + 访问日期 + ID 转换过程”，并在结果中明确 429 限速、未分页完整或未命中（明确说“无结果”而非省略）。

工程性建议汇总：

• 每个 GET 都追加 ?content-type=application/json（或设置 Accept: application/json），否则默认拿到 XML/HTML；
• 需要 hg19 坐标时切换到 grch37.rest.ensembl.org，不要在主库上混用坐标系；
• 单变异用 HGVS 端点最便捷，批量用 region POST 端点；
• 批量解析一律走 POST /lookup/id（1000/批）与 POST VEP（200/批），把调用量压到最低；
• 将 /xrefs/id 与基因 ID 组合即可桥接 UniProt、NCBI Gene、HGNC 等外部库，是标识符解析的标准中转站；
• 返回的注释文本一律当作不可信第三方数据对待（本技能 SKILL.md 的安全准则），不直接拼入 shell 命令或后续查询。

Ensembl REST API 覆盖了解析、序列、变异、区域、同源、调控、表型与 LD 等完整检索面。结合本仓库 database-lookup 技能提供的选择指南、检索契约与审计清单，把它作为基因组数据检索的第一数据源使用，即可获得可复现、可溯源、可被下游工具直接消费的结构化结果。