# 数据查询 API

## 请求约定

网关路径前缀为 `/api/relic`。以下 POST 端点均执行读取请求。

| 字段           | 定义                                     |
| -------------- | ---------------------------------------- |
| Accept-Version | 请求头，当前契约版本为 1                 |
| datasetRef     | 服务生成的不透明数据集句柄               |
| page.cursor    | 续页游标，对应上一页响应中的 page.cursor |
| page.limit     | 每页条数                                 |

## 接口

| 方法与路径                   | 内容                             |
| ---------------------------- | -------------------------------- |
| POST /api/relic/search       | 按活动聚合的检索结果与数据集摘要 |
| POST /api/relic/lookup       | 批量数据集详情                   |
| GET /api/relic/sources       | 数据源、版本与系统模型目录       |
| POST /api/relic/lci          | 某数据集的累积基本流清单         |
| POST /api/relic/lcia         | 某数据集的 LCIA 结果             |
| POST /api/relic/lcia-methods | 指定数据源与版本的 LCIA 方法目录 |

## 检索字段

| /search 请求字段        | 定义                                         |
| ----------------------- | -------------------------------------------- |
| query                   | 参考产品、名称或描述关键词，可省略           |
| filters.sources         | 数据源及版本范围                             |
| filters.models          | 系统模型范围                                 |
| filters.locations       | 地理代码范围                                 |
| filters.activityTypes   | 活动类型范围                                 |
| filters.classifications | 分类范围                                     |
| sort                    | name 或 relevance；相关性排序要求 query 非空 |
| page                    | 游标及每页条数，每页最多 100 条              |

字段之间按 AND 组合，同一字段的多值按 OR 匹配。data 为活动数组，datasets 为对应数据集摘要，page.total 为命中活动数。

## 详情字段

| /lookup 请求字段 | 定义                                        |
| ---------------- | ------------------------------------------- |
| datasetRefs      | 数据集句柄数组，与 coordinates 二选一       |
| coordinates      | 坐标数组；每项包含 id、version、systemModel |
| include          | documentation、provenance；默认包含二者     |

每次最多查询 200 项。未找到的记录返回 found: false。

下表为数据集详情中的地理与参考产品字段；XLSX 对应列见 [Geographies](/resources/file-definitions#geographies)
和[模型目录列](/resources/file-definitions#database-overview)。

| /lookup 响应字段        | 定义                 |
| ----------------------- | -------------------- |
| location.id             | 数据集地理标识       |
| location.name           | 地理名称             |
| location.path           | 已有地理路径，可为空 |
| referenceProduct.amount | 参考产品数量         |
| referenceProduct.unit   | 参考产品单位         |

## 结果字段

| 接口          | 主要请求字段                                            | 主要响应字段                                                         |
| ------------- | ------------------------------------------------------- | -------------------------------------------------------------------- |
| /lci          | datasetRef；可选 type、name、flowCategory、page         | flow、amount、unit、direction                                        |
| /lcia         | datasetRef；可选 methodId、categories、indicators、page | method、value、unit                                                  |
| /lcia-methods | source；可选 version、query、page                       | data.methods 中的 methodId、name、category、indicator、unit、version |

| 查询          | 每页上限 | 结果范围                                    |
| ------------- | -------: | ------------------------------------------- |
| /lci          |      200 | 累积基本流，不含参考产品；单位缺失时为 null |
| /lcia         |      200 | 影响评价方法、影响类别和类别指标对应的结果  |
| /lcia-methods |      500 | 数据源与版本对应的影响评价方法目录          |

累积 LCI 的 amount / unit 表示基本流数量与计量单位；LCIA 的 value / unit 表示影响评价结果与类别指标单位。

/lcia 的 methodId、categories、indicators 取值来自相应数据源的方法目录。methodId 使用完整的
[Method ID](/resources/file-definitions#impact-categories)，不是单独的 [Method UUID](/resources/file-definitions#lcia-methods)。

## 响应

| 字段            | 内容                                            |
| --------------- | ----------------------------------------------- |
| data            | 查询数据，结构随端点而不同                      |
| page            | cursor、limit、total；cursor 为空表示没有后续页 |
| meta            | 契约版本、语言与发布集元数据                    |
| restricted      | /lci、/lcia 的结果受限标志                      |
| data.restricted | /lcia-methods 的目录受限标志                    |
| error           | code、message、field、details、requestId        |

商业数据未授权时，/lci、/lcia 返回空 data 及 restricted: true；/lcia-methods 返回空 methods 及 data.restricted:
true。查询接口不返回单元过程直接交换、供应份额或特征化因子数值表。