分类

`GET /api/v1/taxonomy/tree/roots`

返回顶层根节点及其子节点数量，用于渐进式展开分类树。

curl "https://api.ilepbase.com/api/v1/taxonomy/tree/roots?page=1&pageSize=50"

查询参数

名称	类型	必填	默认值	描述
`page`	`int`	否	`1`	页码。
`pageSize`	`int`	否	`50`	每页条目数，最大 200。

响应

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "name": "Lepidoptera",
        "rank": "order",
        "depth": 1,
        "childCount": 126,
        "hasDetail": true
      }
    ],
    "pagination": {
      "page": 1, "pageSize": 50,
      "total": 1, "totalPages": 1,
      "hasNext": false, "hasPrev": false
    }
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

`GET /api/v1/taxonomy/tree/children`

返回指定父级分类节点下的子节点。

curl "https://api.ilepbase.com/api/v1/taxonomy/tree/children?parentId=1&page=1&pageSize=50"

查询参数

名称	类型	必填	默认值	描述
`parentId`	`int`	是	—	父节点 ID。
`page`	`int`	否	`1`	页码。
`pageSize`	`int`	否	`50`	每页条目数，最大 200。

响应

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 2,
        "name": "Papilionidae",
        "rank": "family",
        "depth": 2,
        "childCount": 31,
        "hasDetail": false
      }
    ],
    "parentId": 1,
    "pagination": {
      "page": 1, "pageSize": 50,
      "total": 126, "totalPages": 3,
      "hasNext": true, "hasPrev": false
    }
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

错误：400 Bad Request

{
  "success": false,
  "error": {
    "code": "MISSING_PARENT_ID",
    "message": "Query parameter 'parentId' is required."
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

`GET /api/v1/taxonomy/search`

在分类树中进行全文检索。支持科学名与异名检索，并返回带 HTML 高亮的结果。

curl "https://api.ilepbase.com/api/v1/taxonomy/search?q=papilio&limit=20"

查询参数

名称	类型	必填	默认值	描述
`q`	`string`	是	—	搜索关键词。
`limit`	`int`	否	`20`	最大结果数，最高 100。

`GET /api/v1/taxonomy/typeahead`

基于前缀的分类节点联想检索。返回科学名、俗名与父级上下文。

curl "https://api.ilepbase.com/api/v1/taxonomy/typeahead?q=Pap&limit=10"

查询参数

名称	类型	必填	默认值	描述
`q`	`string`	是	—	前缀关键词，至少 2 个字符。
`limit`	`int`	否	`10`	最大结果数，最高 20。

错误：503 Service Unavailable

{
  "success": false,
  "error": {
    "code": "TYPEAHEAD_UNAVAILABLE",
    "message": "Typeahead service is unavailable."
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

`GET /api/v1/taxonomy/nodes/{nodeId}`

返回分类节点的完整详情负载。

curl https://api.ilepbase.com/api/v1/taxonomy/nodes/1

响应

{
  "success": true,
  "data": {
    "node": {
      "id": "order-lepidoptera",
      "name": "Lepidoptera",
      "rank": "Order",
      "detailId": "order-lepidoptera"
    },
    "detail": {
      "id": "order-lepidoptera",
      "title": "Lepidoptera",
      "rank": "Order",
      "summary": "Lepidoptera comprises butterflies and moths, with approximately 180,000 described species worldwide...",
      "image": "/assets/images/home/u50.png",
      "links": [
        { "label": "GBIF", "href": "https://www.gbif.org/species/1852787" }
      ],
      "metrics": [
        { "label": "Families", "value": "126" },
        { "label": "Species", "value": "114,852" }
      ],
      "omics": {
        "summary": "Multi-omics data available for selected species.",
        "items": [
          { "label": "Genomes", "value": "48 assemblies" },
          { "label": "Transcriptomes", "value": "24 datasets" }
        ]
      },
      "ecology": {
        "summary": "Hostplant associations and distribution data.",
        "items": [
          { "label": "Hostplant Records", "value": "3,200+" }
        ]
      },
      "literature": {
        "summary": "Key publications referencing this taxon.",
        "publications": [
          {
            "title": "A comprehensive phylogeny of Lepidoptera...",
            "citation": "Kawahara et al., 2019, PNAS",
            "href": "https://doi.org/10.1073/pnas.1907842116",
            "tags": ["phylogeny", "transcriptome"]
          }
        ],
        "graph": {
          "nodes": [ ... ],
          "edges": [ ... ]
        }
      },
      "genetics": "Lepidoptera have a ZW sex-determination system...",
      "morphology": "Adults characterized by two pairs of membranous wings covered in scales..."
    }
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

`GET /api/v1/taxonomy/nodes/{nodeId}/literature`

分页返回与某个分类节点关联的文献。

curl "https://api.ilepbase.com/api/v1/taxonomy/nodes/1/literature?page=1&pageSize=20"

查询参数

名称	类型	必填	默认值	描述
`page`	`int`	否	`1`	页码。
`pageSize`	`int`	否	`20`	每页条目数。

路径参数

名称	类型	描述
`nodeId`	`int`	分类节点 ID。

分类

目录