夜雨聆风学习资料网

ARTICLE · 1396389

咖啡因摄入计算 API 接口文档(数据鱼API)

咖啡因摄入计算 API 接口文档(数据鱼API)

接口简介

「咖啡因摄入计算」是数据鱼API平台提供的饮品咖啡因摄入量计算接口,Base 路径 /api/caffeine,共 6 个端点。咖啡因摄入计算接口(caffeine)内置 48 种常见饮品的咖啡因含量库,提供四类计算能力:单品摄入量换算(drink)、全天累计与建议上限对照(day)、睡前最后饮用时点推算(cutoff)、饮品库检索(drinks)。含量按每 100 毫升常见区间的中值取数,接口在 note 字段中提示以产品标签为准。

上限口径为一般健康人群建议:健康成人 400 毫克/日,孕妇 200 毫克/日,青少年按体重每公斤 3 毫克/日。半衰期按约 5 小时估算,cutoff 端点据此推算睡前剩余摄入量与逐段衰减表。数据鱼API 的该接口在所有计算响应中携带 note 与 disclaimer 字段,说明数据口径与适用人群限制。

端点总览

方法
路径
说明
鉴权
GET
/api/caffeine/ping
健康检查
文档标注免鉴权,实测需携带 Key
GET
/api/caffeine/stats
服务与数据统计(饮品数、分类、上限、间隔)
是
GET
/api/caffeine/drink
单品咖啡因换算
是
GET
/api/caffeine/day
全天累计对照建议上限
是
GET
/api/caffeine/cutoff
睡前停饮时点推算
是
GET
/api/caffeine/drinks
饮品库列表,可按分类过滤
是

通用约定

  • 鉴权:与数据鱼API 平台其他接口一致,X-API-Key 请求头或 ?api_key= 查询参数均可;4011/4013 全站通用。
  • 响应为统一 code/msg/data 结构;参数缺失或非法返回 4001/4002。
  • 全部端点仅接受 GET,POST 返回 4050;计算响应均带 note 与 disclaimer 字段。

核心端点详解

drink 单品换算

参数
类型
必填
默认
说明
name
string
是
—
饮品名或别名,如 美式、americano
ml
number
二选一
—
液体容量(毫升)
grams
number
二选一
—
重量(克),液体饮品会拒绝该参数

返回字段要点:name 为库内标准名;matched_input 回显实际命中的输入词;category 为分类;caffeine_mg 为换算后的摄入量;percent_of_limit 为占成人 400 毫克上限的比例;note 给出含量区间说明。

GET /api/caffeine/drink?name=美式&ml=350&api_key=YOUR_KEY
{   "code": 0,   "msg": "success",   "data": {     "name": "美式咖啡",     "matched_input": "美式",     "category": "咖啡",     "amount_ml": 350,     "caffeine_mg": 133,     "percent_of_limit": 33.3,     "limit_basis": "成人每日建议上限 400mg (健康成人)"   } }

day 全天累计

参数
类型
必填
默认
说明
items
string
是
—
JSON 数组字符串,如 [{"name":"美式","ml":350}],最多 10 项
group
string
否
adult
adult / pregnant / teen
weight
number
否
—
体重(公斤),teen 组按体重计上限,取值 20–150

返回字段要点:total_mg 为合计摄入量;limit_mg 为对应人群上限;percent_of_limit、remaining_mg、over_mg 给出对照;超过上限时 warning 字段给出建议文本并提示就医情形。

GET /api/caffeine/day?items=[{"name":"美式","ml":350}]&group=adult&api_key=YOUR_KEY
{   "code": 0,   "msg": "success",   "data": {     "total_mg": 133,     "limit_mg": 400,     "percent_of_limit": 33.3,     "remaining_mg": 267,     "over_mg": 0,     "warning": null   } }

cutoff 睡前停饮推算

参数
类型
必填
默认
说明
bedtime
string
是
—
计划入睡时间,HH:MM
sensitivity
string
否
mid
low / mid / high,对应睡前安全间隔 4 / 6 / 9 小时

返回字段要点:last_drink 为按安全间隔倒推的最后饮用时点;assumption_mg 说明按 100 毫克(约一杯标准咖啡)推算,其他摄入量按比例缩放;half_life_hours 为 5;bedtime_remaining_mg 为入睡时刻体内剩余量;table 为按半衰期逐段衰减的时间表。

GET /api/caffeine/cutoff?bedtime=23:00&sensitivity=mid&api_key=YOUR_KEY
{   "code": 0,   "msg": "success",   "data": {     "bedtime": "23:00",     "sensitivity": "mid",     "gap_hours": 6,     "last_drink": "17:00",     "half_life_hours": 5,     "bedtime_remaining_mg": 43.5   } }

数据与限制

  • 饮品库 48 种,分类为咖啡 14、茶 15、奶茶 4、碳酸 5、能量饮料 4、其他 6;含量为常见区间中值,以产品标签为准。
  • day 单次最多 10 项;weight 取值 20–150 公斤,超出返回 4002。
  • drink 的 ml 与 grams 二选一,同时传入返回 4002;液体饮品传 grams 会被拒绝。
  • drinks 可不带分类返回全部 48 条,或按 stats 中的分类名过滤;未收录分类返回 4004。
  • 无上游依赖,响应即时;stats 端点可随时读取条数与口径说明。

典型使用场景

  • 健康记录应用里做咖啡因日摄入打卡与上限对照。
  • 睡眠改善工具中计算睡前应停饮的时点。
  • 咖啡、奶茶点单助手展示单杯摄入占比。

注意事项

  • 含量为常见区间中值的近似值,连锁门店因粉水比不同差异明显,现制饮品尤其如此,以产品标签为准。
  • 半衰期 5 小时为一般人群均值,个体差异大;上限为健康人群一般建议,孕妇、心律不齐、焦虑等人群应遵医嘱。
  • sensitivity 的取值未在文档参数表中限定,实测仅接受 low / mid / high,其他值返回 4002。
  • 时间跨零点时,衰减表中的时刻按次日或前一日理解,调用方需自行处理跨天展示。
  • 本接口全部计算结果仅供参考,不构成健康或医疗建议。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料