Simple Food Nutrition API

Get instant access to comprehensive food nutrition data. Search any food item and retrieve detailed nutritional information including calories, macronutrients (protein, carbs, fat), serving sizes, brand names, and complete nutrient profiles. Perfect for fitness apps, meal planners, calorie trackers, health calculators, and nutrition analysis tools. Simple REST API with clean JSON responses and robust error handling.

原始信息汇总

Simple Food Nutrition API 数据集概述

基本信息

• 数据集名称：Simple Food Nutrition API
• 数据来源：USDA FoodData Central 数据库
• 数据规模：包含超过 300,000 种食品项目
• 数据内容：食品营养数据，包括卡路里、宏量营养素（蛋白质、碳水化合物、脂肪）、份量、品牌名称和完整的营养成分表

主要功能

• 综合性数据库：可搜索超过 300,000 种食品项目
• 完整的营养数据：提供卡路里、宏量营养素、份量及详细的营养成分表
• 灵活的搜索：支持按食品名称、类型或品牌进行搜索，并可自定义结果数量限制
• 清晰的 JSON 响应：结构良好、易于解析的数据格式
• 健壮的错误处理：全面的验证和清晰的错误信息
• 速率限制：每个 IP 地址每 15 分钟 100 次请求

API 端点

GET /

欢迎端点，返回 API 信息和文档。

GET /foods

按类型搜索食品项目并获取详细的营养信息。

• 必需查询参数：type（食品类型或名称，例如：apple、chicken breast、whole wheat bread）
• 可选查询参数：limit（最大结果数，默认值：25，最大值：200）
• 响应字段：
  • fdcId：食品数据中心 ID（唯一标识符）
  • description：食品项目名称和描述
  • dataType：数据类型（Foundation、Branded 等）
  • publicationDate：数据发布日期
  • brandOwner：品牌名称（如适用，无品牌项目为 null）
  • ingredients：成分列表（如可用）
  • foodNutrients：营养成分数组，包含：
    • nutrientId：营养成分标识符
    • nutrientName：营养成分名称
    • unitName：计量单位（g、kcal、mg 等）
    • value：营养成分值

GET /health

健康检查端点，用于验证 API 和 USDA 服务状态。

• 状态值：
  • operational：服务正常运行
  • degraded：服务出现问题
  • unreachable：无法访问服务
  • not_configured：服务未配置
  • api_key_invalid：API 密钥无效

使用场景

• 健身应用：卡路里计数器、宏量营养素追踪器和饮食计划应用
• 膳食计划工具：具有自动营养计算和食谱分析的备餐应用
• 营养计算器：膳食分析、营养目标追踪和食物记录工具
• 健康与保健平台：将食品数据集成到健康仪表板和保健计划中
• 食谱应用：计算食谱和膳食组合的营养价值
• 电子商务：在线商店中显示食品产品的营养信息
• 教育工具：构建营养教育平台和食品数据库浏览器

错误处理

API 返回标准的 HTTP 状态码及清晰的错误信息。

• 400 Bad Request：查询参数无效或缺少必填字段

速率限制

• 限制：每个 IP 地址每 15 分钟 100 次请求
• 标头：速率限制信息包含在响应标头中
• 超出限制：返回 429 Too Many Requests 及相应信息

搜索提示

• 具体查询：使用具体的食品名称以获得更好的结果（例如，使用“Granny Smith apple”而不仅仅是“apple”）
• 多词查询：对多词搜索使用引号或 URL 编码（例如，“chicken breast”或chicken%20breast）
• 特殊字符：支持连字符和撇号（例如，“ice-cream”、“oatmeal”）
• 限制结果：使用 limit 参数控制结果数量（默认值：25，最大值：200）
• 不区分大小写：搜索不区分大小写

认证

所有请求都需要通过 RapidAPI 进行认证。使用 RapidAPI 界面时，这些标头会自动包含。

响应格式

所有响应均以 UTF-8 编码的 JSON 格式返回。

• 成功响应：
  • 状态码：200
  • Content-Type：application/json
  • 正文：包含请求数据的 JSON 对象
• 错误响应：
  • 状态码：4xx 或 5xx
  • Content-Type：application/json
  • 正文：包含错误详情的 JSON 对象

最佳实践

1. 缓存结果：食品数据不经常更改，因此尽可能缓存结果
2. 使用适当的限制：仅请求所需数量的结果
3. 优雅地处理错误：对 4xx 和 5xx 响应实施适当的错误处理
4. 遵守速率限制：监控请求速率以避免达到限制
5. 验证输入：在发出 API 请求之前验证用户输入
6. 使用健康端点：定期检查 /health 端点以监控 API 状态

常见问题

• Q: 我可以请求的最大结果数是多少？
  A: 每个请求的最大限制是 200 个结果。默认值为 25。
• Q: 我可以搜索品牌产品吗？
  A: 可以！数据库包含品牌和无品牌产品。品牌产品的 brandOwner 字段将被填充。
• Q: 数据多久更新一次？
  A: 数据会定期更新。请检查 publicationDate 字段以获取特定项目的更新日期。
• Q: 响应中包含哪些营养成分？
  A: USDA 数据库中所有可用的营养成分都包含在 foodNutrients 数组中。这包括卡路里、宏量营养素、维生素、矿物质等。
• Q: 我可以一次搜索多种食物吗？
  A: 每个请求搜索一种食物类型。对于不同的食物，请发出多个请求，或使用 limit 参数从单个搜索中获取更多结果。
• Q: 有速率限制吗？
  A: 是的，API 的速率限制为每个 IP 地址每 15 分钟 100 次请求。

搜集汇总

背景与挑战

背景概述

该数据集提供全面的食物营养信息API服务，可查询各类食物的详细营养成分（如热量、宏量营养素等），支持健身应用、膳食计划等场景。采用REST架构，返回结构化的JSON数据。