学术文献检索

按关键词检索学术文献，返回标题、作者、年份、期刊、DOI、被引次数和开放获取链接，可按出版年份过滤。


接口	`POST /v1/scholarly-searches`
所需权限	`scholarly_search:search`
MCP 工具	`scholarly_search`
计量单位	`works`

计量单位出现在 execution.usage.units 中，用于对账和计费。

请求字段

字段	类型	必填	说明
`invocation_id`	string	是	调用方（市场）生成的调用 ID：同一个 ID 在同一操作上只执行一次，用同一 ID 重试会被拒绝而不会重复计费。1–128 个字符，可用 A-Z a-z 0-9 . _ : -。
`provider`	string	是	处理本次请求的数据源，按下方数据源表的覆盖范围选择。可选值：`crossref`, `openalex`
`query`	string	是	检索关键词，1–300 个字符。
`from_year`	integer	否	可选，最早出版年份，1000 到明年，不能大于 to_year。
`max_results`	integer	否	返回的文献数量，1–25，默认 10。
`to_year`	integer	否	可选，最晚出版年份，1000 到明年，不能小于 from_year。

数据源

数据源	区域	说明	限制
`crossref`	US	Crossref，覆盖 Crossref 注册的 DOI	`max_results`: 25, `timeout_seconds`: 30
`openalex`	US	OpenAlex，覆盖面最广的跨学科目录	`max_results`: 25, `timeout_seconds`: 30

示例

curl -sS https://services.zgi.im/v1/scholarly-searches \
  -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"invocation_id": "docs-1791778521-scholarly_search", "provider": "openalex", "query": "graph neural networks", "max_results": 2}'

POST /v1/scholarly-searches HTTP/1.1
Host: services.zgi.im
Authorization: Bearer <token>
Content-Type: application/json

{
  "invocation_id": "docs-1791778521-scholarly_search",
  "provider": "openalex",
  "query": "graph neural networks",
  "max_results": 2
}

通过 MCP 调用时，工具参数与 HTTP 请求体完全相同。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scholarly_search",
    "arguments": {
      "invocation_id": "docs-1791778521-scholarly_search",
      "provider": "openalex",
      "query": "graph neural networks",
      "max_results": 2
    }
  }
}

curl -sS https://services.zgi.im/v1/mcp \
  -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d @request.json

以下为一次真实调用的返回，列表只保留前两项，长文本已截断。

{
  "code": 0,
  "message": "success",
  "data": {
    "execution": {
      "id": "exe_01a12e52bb9278c58ae2e160782b5430",
      "invocation_id": "docs-1791778521-scholarly_search",
      "capability": "scholarly_search",
      "operation": "scholarly_search.search",
      "provider": "openalex",
      "outcome": "succeeded",
      "error_category": null,
      "error_code": null,
      "usage": {
        "provider_requests": 1,
        "units": [
          {
            "name": "works",
            "value": 2,
            "source": "measured"
          }
        ]
      },
      "upstream_ref": null,
      "request_id": "req_193791742237ef76fe24671a",
      "started_at": "2026-10-12T04:15:36.338572607Z",
      "finished_at": "2026-10-12T04:15:36.771329958Z",
      "duration_ms": 432
    },
    "result": {
      "total_results": 988681,
      "works": [
        {
          "title": "Graph neural networks",
          "doi": "10.1038/s43586-024-00294-7",
          "year": 2024,
          "type": "review",
          "venue": "Nature Reviews Methods Primers",
          "authors": [
            "Gabriele Corso",
            "Hannes Stark"
          ],
          "cited_by_count": 457,
          "url": "https://openalex.org/W4392553889",
          "open_access_url": null
        },
        {
          "title": "The Graph Neural Network Model",
          "doi": "10.1109/tnn.2008.2005605",
          "year": 2008,
          "type": "article",
          "venue": "IEEE Transactions on Neural Networks",
          "authors": [
            "Franco Scarselli",
            "M. Gori"
          ],
          "cited_by_count": 9708,
          "url": "https://openalex.org/W2116341502",
          "open_access_url": "https://figshare.com/articles/journal_contribution/The_graph_neural_network_model/27757629"
        }
      ],
      "source": {
        "name": "OpenAlex",
        "license": "CC0-1.0",
        "url": "https://openalex.org"
      }
    }
  }
}