ARTICLE · 1396389
咖啡因摄入计算 API 接口文档(数据鱼API)
接口简介
「咖啡因摄入计算」是数据鱼API平台提供的饮品咖啡因摄入量计算接口,Base 路径 /api/caffeine,共 6 个端点。咖啡因摄入计算接口(caffeine)内置 48 种常见饮品的咖啡因含量库,提供四类计算能力:单品摄入量换算(drink)、全天累计与建议上限对照(day)、睡前最后饮用时点推算(cutoff)、饮品库检索(drinks)。含量按每 100 毫升常见区间的中值取数,接口在 note 字段中提示以产品标签为准。
上限口径为一般健康人群建议:健康成人 400 毫克/日,孕妇 200 毫克/日,青少年按体重每公斤 3 毫克/日。半衰期按约 5 小时估算,cutoff 端点据此推算睡前剩余摄入量与逐段衰减表。数据鱼API 的该接口在所有计算响应中携带 note 与 disclaimer 字段,说明数据口径与适用人群限制。
端点总览
通用约定
鉴权:与数据鱼API 平台其他接口一致, X-API-Key请求头或?api_key=查询参数均可;4011/4013 全站通用。响应为统一 code/msg/data结构;参数缺失或非法返回 4001/4002。全部端点仅接受 GET,POST 返回 4050;计算响应均带 note 与 disclaimer 字段。
核心端点详解
drink 单品换算
返回字段要点: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 全天累计
返回字段要点: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 睡前停饮推算
返回字段要点: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。 时间跨零点时,衰减表中的时刻按次日或前一日理解,调用方需自行处理跨天展示。 本接口全部计算结果仅供参考,不构成健康或医疗建议。















































































