接口简介
「BI 看板计算助手」是数据鱼API平台提供的轻量统计计算接口,Base 路径 /api/bi-dashboard-helper,共 5 个端点。aggregate 对一组数值做聚合统计,predict 用一次指数平滑(Simple Exponential Smoothing)对时间序列做下一期预测。它面向 BI 看板与数据小工具的开发场景:前端已经拿到一列指标数据,需要快速补充均值、中位数、极值或一条预测线时,不必在前端重复实现统计代码,也不必为此引入数据库或重型分析组件。
接口是完全无状态、无数据源的纯计算服务:请求里带什么数据就算什么数据,不连接任何数据库,也不缓存历史请求。aggregate 同时输出计数、合计、均值、最小值、最大值与中位数六个统计量,predict 输出逐期拟合值序列与下一期预测值,并在 confidence 字段标注算法来源。
数据鱼API 将其定位为看板辅助件:两个端点均支持 GET 与 POST 等价调用,复杂结构的参数(数组、对象数组)建议走 POST JSON body。
端点总览
方法 路径 说明 鉴权
GET /api/bi-dashboard-helper/ping 健康检查,返回服务名与版本号 需要
GET /api/bi-dashboard-helper/aggregate 聚合统计(参数可放 query 的 JSON 字符串) 需要
POST /api/bi-dashboard-helper/aggregate 聚合统计(JSON body 传数组) 需要
GET /api/bi-dashboard-helper/predict 指数平滑预测(参数可放 query 的 JSON 字符串) 需要
POST /api/bi-dashboard-helper/predict 指数平滑预测(JSON body 传序列) 需要
通用约定
鉴权使用数据鱼API 全站统一的 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011,无效返回 4013(文档将 ping 标注为免鉴权,实测仍需携带 Key)。响应为统一三段结构 {code, msg, data};缺参返回 4001(如 Missing data or metric、Missing data series),参数类型不符返回 4002 并指明期望类型。GET 与 POST 参数名一致;数组、对象等结构化参数用 JSON body 或 JSON 字符串传递。
核心端点详解
聚合统计 aggregate
对数值数组或对象数组计算一组统计量。
参数 类型 必填 默认 说明
data array 是 — 数值数组,或对象数组(配合 metric 指定字段名)
metric string 视情况 — 对象数组时指定参与统计的字段名;数值数组可省略
返回字段要点:total 合计、average 均值(保留四位小数)、count 参与统计的条数、min/max/median 极值与中位数;对象数组时 field 回显实际使用的字段名。实测数值数组 [120,200,80] 返回 total 400、average 133.3333、count 3、min 80、max 200、median 120;对象数组 [{"x":1,"y":2},{"x":2,"y":4},{"x":3,"y":6}] 传 metric: "y" 返回 total 12、average 4、median 4。
POST /api/bi-dashboard-helper/aggregate?api_key=YOUR_KEY
Content-Type: application/json
{"data": [120, 200, 80], "metric": "value"}
{"code": 0, "msg": "success", "data": {"metric": "value", "field": "value", "total": 400, "average": 133.3333, "count": 3, "min": 80, "max": 200, "median": 120}}
当 data 是对象数组且 metric 指定的字段名在元素中不存在时,接口不报错,返回 count 0 与 note 提示「data 中未找到可计算的数值字段」,客户端应检查 note 再决定是否提示用户。
指数平滑预测 predict
按一次指数平滑递推拟合历史序列并给出下一期预测。
参数 类型 必填 默认 说明
series array 是 — 数值型时间序列,需以 JSON 数组传递
alpha number 否 0.3 平滑系数,建议 0–1
返回字段要点:historical_forecast 为逐期拟合值序列(首期取原值);next_period_prediction 为下一期预测值;confidence 固定为「Moderate (Simple Exponential Smoothing)」,说明算法为简单指数平滑、不含季节与趋势项。实测序列 [10,12,13,15,16,18]、alpha 0.3 返回拟合序列 [10, 10, 10.6, 11.32, 12.42, 13.5]、预测值 14.85;alpha 0.9 时预测值 17.79,可见 alpha 越大新值权重越高。序列为空或缺失返回 4001「Missing data series」;单元素序列可用,预测值即该元素本身。
POST /api/bi-dashboard-helper/predict?api_key=YOUR_KEY
Content-Type: application/json
{"series": [10, 12, 13, 15, 16, 18], "alpha": 0.3}
{"code": 0, "msg": "success", "data": {"historical_forecast": [10, 10, 10.6, 11.32, 12.42, 13.5], "next_period_prediction": 14.85, "confidence": "Moderate (Simple Exponential Smoothing)"}}
数据与限制
数据形态:data 与 series 都必须是 JSON 数组;实测逗号分隔的字符串(如 "10,12,13")返回 4002「参数 series 需要 array」。
统计量口径:中位数为排序后中位取值,均值保留四位小数;对象数组只统计 metric 指定的单个字段,不支持多字段聚合。
算法边界:predict 是一阶指数平滑,不识别趋势与季节性,置信字段固定为 Moderate;对强趋势序列预测值会系统性偏低。
无状态:不保存任何历史序列,跨请求没有上下文;重复相同请求返回相同结果。
典型使用场景
看板卡片统计:前端表格数据随手算一组 sum/avg/median 徽标,不落库不建任务。
运营周报快算:把每周指标数组送入 predict,给下期指标一条参考线。
联调与原型验证:无需部署计算服务,先用接口验证统计口径再决定是否本地实现。
注意事项
API.md 的示例把 metric 当作聚合函数列表传入(如 ["sum","avg"]),实测 metric 的真实语义是「对象数组中参与统计的字段名」,按示例传法会得到 count 0 与字段未找到的 note;这是文档示例与实现的偏差,以实测为准。
alpha 实测未做 0–1 越界校验,传入 2 不报错但输出异常(拟合序列被截断);集成方应在客户端把 alpha 限制在 0–1。
数值数组调用 aggregate 时 metric 会被原样回显但不参与计算(field 固定为 value);不必为此传聚合函数名。
GET 调用时数组参数需以 JSON 字符串形式放进 query 并做 URL 编码,长度受限,建议数据量大时一律用 POST body。
本接口输出为原始数据的统计描述,不构成任何业务预测承诺;重要决策应结合业务口径复核后再使用预测值。
本接口随数据鱼API 平台统一升级,统计口径与错误分支如有调整,以最新文档为准。