Nutrola的营养数据API：开发者如何访问我们的食品数据库

2026年3月10日

Nutrola的营养数据API开发者指南。了解如何访问我们拥有超过300万条条目的经过验证的食品数据库，探索端点、身份验证和实际使用案例。

Medically reviewed by Dr. Emily Torres, Registered Dietitian Nutritionist (RDN)

正在构建健康、健身或食品相关的应用程序吗？您将面临的最大挑战之一就是营养数据。您需要准确的卡路里和宏观信息，涵盖成千上万的食品，且要包括国际产品，并随着制造商重新配方而保持更新。

大多数开发者会从开放的政府数据库（如USDA FoodData Central）中提取数据。这为您提供了基础，但无法覆盖来自47个国家的品牌产品、餐厅餐点或真实用户每天食用的数千种地方食品。自己填补这些空白意味着需要数年的数据整理工作。

Nutrola的营养数据API为开发者提供了访问与我们应用程序相同的经过验证的食品数据库的权限——超过300万条条目，涵盖原材料、品牌产品、餐厅餐点和复合食谱。每个条目都经过我们多层质量控制流程的验证，这一系统已被超过200万用户信任。

本指南涵盖了您开始使用我们API所需了解的所有内容：架构、身份验证、端点、速率限制以及实际代码示例。

API概述

Nutrola营养数据API是一个RESTful JSON API。您可以发起HTTP请求，获取JSON响应。无需SDK，尽管我们为Python、JavaScript和Swift提供了客户端库以方便使用。

基本URL

https://api.nutrola.com/v1

所有端点均通过HTTPS提供服务。普通HTTP请求将被拒绝。

主要功能

功能	描述
食品搜索	在超过300万条食品条目中进行全文搜索，并按类别、品牌和国家进行过滤
条形码查找	通过UPC、EAN或其他条形码格式获取营养数据
营养详情	获取任何食品的完整营养档案（70多种营养素，包括微量元素）
份量大小	标准和替代份量大小及其克转换
食谱分析	提交成分列表并获取综合营养数据
食品类别	浏览分层的食品类别分类法
品牌目录	搜索和浏览品牌食品制造商
自动补全	提供快速的输入建议以便于食品搜索界面

响应格式

所有响应遵循一致的结构：

{
  "status": "success",
  "data": { },
  "meta": {
    "request_id": "req_abc123",
    "rate_limit_remaining": 245,
    "rate_limit_reset": "2026-03-10T15:00:00Z"
  }
}

错误响应包括机器可读的错误代码和人类可读的消息：

{
  "status": "error",
  "error": {
    "code": "FOOD_NOT_FOUND",
    "message": "没有找到与提供的ID匹配的食品条目。",
    "request_id": "req_xyz789"
  }
}

身份验证

所有API请求都需要在Authorization头中传递API密钥。

获取API密钥

在developer.nutrola.com创建开发者账户
在仪表板中导航到API密钥部分
生成一个新密钥并指定所需的作用域
安全存储密钥——它只会显示一次

使用您的API密钥

在每个请求头中包含密钥：

Authorization: Bearer YOUR_API_KEY

使用curl的示例：

curl -H "Authorization: Bearer ntr_live_abc123def456" \
  https://api.nutrola.com/v1/foods/search?q=chicken+breast

API密钥作用域

作用域	访问级别
`foods:read`	搜索和检索食品数据（最常用）
`barcodes:read`	条形码查找
`recipes:analyze`	食谱营养分析
`brands:read`	品牌目录访问
`categories:read`	食品类别分类法

密钥可以被限制为特定功能。仅具有foods:read的密钥无法访问条形码查找。这遵循最小权限原则——仅请求您的应用程序所需的作用域。

核心端点

食品搜索

按名称、关键字或短语搜索数据库。

GET /v1/foods/search

参数：

参数	类型	必需	描述
`q`	string	是	搜索查询（例如，“烤鸡胸肉”）
`category`	string	否	按食品类别过滤（例如，“乳制品”，“蔬菜”）
`brand`	string	否	按品牌名称过滤
`country`	string	否	ISO 3166-1 alpha-2国家代码（例如，“US”，“DE”，“JP”）
`verified_only`	boolean	否	仅返回具有验证源数据的条目（默认：true）
`page`	integer	否	分页的页码（默认：1）
`per_page`	integer	否	每页结果数，最大50（默认：20）

示例请求：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.nutrola.com/v1/foods/search?q=greek+yogurt&country=US&per_page=5"

示例响应：

{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "food_8f2k9d",
        "name": "希腊酸奶，原味，脱脂",
        "brand": null,
        "category": "乳制品",
        "country": "US",
        "verified": true,
        "source": "USDA",
        "nutrition_per_100g": {
          "calories": 59,
          "protein": 10.2,
          "carbohydrates": 3.6,
          "fat": 0.4,
          "fiber": 0,
          "sugar": 3.2,
          "sodium": 36
        },
        "default_serving": {
          "description": "1容器（170克）",
          "grams": 170
        }
      }
    ],
    "total_results": 342,
    "page": 1,
    "per_page": 5
  }
}

获取食品详情

检索特定食品的完整营养档案。

GET /v1/foods/{food_id}

示例请求：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.nutrola.com/v1/foods/food_8f2k9d"

详细响应包括完整的营养成分细分——超过70种营养素，包括所有维生素、矿物质、氨基酸和脂肪酸档案。它还包括所有可用的份量大小及其克等值。

部分响应（关键营养素）：

{
  "status": "success",
  "data": {
    "id": "food_8f2k9d",
    "name": "希腊酸奶，原味，脱脂",
    "nutrition_per_100g": {
      "calories": 59,
      "protein": 10.2,
      "carbohydrates": 3.6,
      "fat": 0.4,
      "fiber": 0,
      "sugar": 3.2,
      "saturated_fat": 0.1,
      "monounsaturated_fat": 0.1,
      "polyunsaturated_fat": 0,
      "cholesterol": 5,
      "sodium": 36,
      "potassium": 141,
      "calcium": 110,
      "iron": 0.1,
      "vitamin_a": 4,
      "vitamin_c": 0,
      "vitamin_d": 0
    },
    "serving_sizes": [
      { "description": "1容器（170克）", "grams": 170 },
      { "description": "1杯（245克）", "grams": 245 },
      { "description": "1汤匙（15克）", "grams": 15 },
      { "description": "100克", "grams": 100 }
    ],
    "allergens": ["牛奶"],
    "source": "USDA",
    "source_id": "170903",
    "last_verified": "2026-02-15",
    "confidence_score": 0.98
  }
}

条形码查找

通过条形码查找食品产品。

GET /v1/barcodes/{barcode}

支持格式： UPC-A, UPC-E, EAN-13, EAN-8

示例请求：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.nutrola.com/v1/barcodes/0049000006346"

响应返回与/foods/{food_id}端点相同的食品详细对象，附加条形码特定字段，如barcode_format和regional_variants（不同国家同一产品的食品ID数组，可能具有不同配方）。

食谱分析

提交成分列表并接收综合营养细分。

POST /v1/recipes/analyze

请求体：

{
  "name": "过夜燕麦",
  "servings": 2,
  "ingredients": [
    { "food_id": "food_3k8m2n", "grams": 160 },
    { "food_id": "food_9p4q7r", "grams": 400 },
    { "food_id": "food_1a5b8c", "grams": 60 },
    { "food_id": "food_6d2e9f", "grams": 2, "description": "一小撮盐" }
  ]
}

您也可以提交成分文本以进行自动解析：

{
  "name": "过夜燕麦",
  "servings": 2,
  "ingredients_text": "160克燕麦，400毫升全脂牛奶，60克花生酱，一小撮盐"
}

响应：

{
  "status": "success",
  "data": {
    "name": "过夜燕麦",
    "servings": 2,
    "nutrition_per_serving": {
      "calories": 425,
      "protein": 18.5,
      "carbohydrates": 42.3,
      "fat": 21.2,
      "fiber": 5.8
    },
    "nutrition_total": {
      "calories": 850,
      "protein": 37.0,
      "carbohydrates": 84.6,
      "fat": 42.4,
      "fiber": 11.6
    },
    "ingredients_matched": [
      { "input": "160克燕麦", "matched_food": "food_3k8m2n", "confidence": 0.97 },
      { "input": "400毫升全脂牛奶", "matched_food": "food_9p4q7r", "confidence": 0.99 },
      { "input": "60克花生酱", "matched_food": "food_1a5b8c", "confidence": 0.96 },
      { "input": "一小撮盐", "matched_food": "food_6d2e9f", "confidence": 0.88 }
    ]
  }
}

自动补全

为构建搜索界面提供快速的输入建议。

GET /v1/foods/autocomplete?q={query}

参数：

参数	类型	必需	描述
`q`	string	是	部分搜索查询（至少2个字符）
`limit`	integer	否	最大结果数，1-10（默认：5）
`country`	string	否	优先考虑来自该国的结果

响应时间经过优化以适应交互使用——通常在50毫秒以内。自动补全端点返回简化的食品对象（仅ID、名称、品牌和类别），以便快速渲染。

速率限制和定价

免费层

免费层旨在用于开发、测试和小规模应用：

限制	值
每日请求	500
每分钟请求	30
每请求食品搜索结果	20
每日食谱分析	10
每日条形码查找	100

增长层

适用于中等流量的生产应用：

限制	值
每日请求	25,000
每分钟请求	300
每请求食品搜索结果	50
每日食谱分析	500
每日条形码查找	5,000
价格	$49/月

企业层

适用于高流量应用、白标解决方案和定制需求：

特性	详情
每日请求	自定义（通常100K以上）
速率限制	自定义
专属支持	包含
SLA	99.9%正常运行时间保证
自定义数据导出	可用
Webhook通知	可用于数据更新
价格	联系销售

速率限制信息包含在每个API响应的meta对象中，并在HTTP响应头中（X-RateLimit-Remaining，X-RateLimit-Reset）。

实际使用案例

健身和锻炼应用

如果您正在构建健身应用并希望添加营养追踪，而不必从头构建食品数据库，Nutrola的API是最快的途径。使用食品搜索和条形码端点，让用户记录餐点，使用食谱分析端点进行自定义餐点输入。

餐饮计划平台

餐饮计划应用需要准确的营养数据，以生成达到特定宏观目标的计划。API的详细营养细分（70多种营养素）使得精确的餐饮计划优化成为可能，不仅仅是卡路里和宏观，还包括微量营养素、过敏原和饮食限制兼容性。

医疗和远程医疗

监测患者营养的医疗平台可以与API集成，以在其现有界面中提供准确的食品记录。经过验证的数据源（USDA、EFSA、制造商直接）符合临床营养监测所需的准确性标准。

餐厅和食品服务

餐厅点餐平台可以使用API显示菜单项的营养信息。食谱分析端点在这里特别有用——提交一道菜的成分，获取完整的营养细分，而无需手动计算每个项目。

研究和学术

营养研究人员可以使用API在饮食研究中标准化食品编码。一致的、经过验证的数据减少了依赖参与者报告的营养数据所带来的测量误差。

代码示例

Python：搜索食品并获取营养详情

import requests

API_KEY = "ntr_live_your_key_here"
BASE_URL = "https://api.nutrola.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

# 搜索食品
search_response = requests.get(
    f"{BASE_URL}/foods/search",
    headers=headers,
    params={"q": "烤鸡胸肉", "per_page": 3}
)

results = search_response.json()["data"]["results"]

for food in results:
    print(f"{food['name']} - {food['nutrition_per_100g']['calories']} cal/100g")

# 获取第一个结果的完整详情
food_id = results[0]["id"]
detail_response = requests.get(
    f"{BASE_URL}/foods/{food_id}",
    headers=headers
)

food_detail = detail_response.json()["data"]
nutrition = food_detail["nutrition_per_100g"]

print(f"\n{food_detail['name']}")
print(f"卡路里: {nutrition['calories']}")
print(f"蛋白质: {nutrition['protein']}g")
print(f"碳水化合物: {nutrition['carbohydrates']}g")
print(f"脂肪: {nutrition['fat']}g")
print(f"份量大小: {food_detail['serving_sizes']}")

JavaScript：条形码扫描集成

const API_KEY = "ntr_live_your_key_here";
const BASE_URL = "https://api.nutrola.com/v1";

async function lookupBarcode(barcode) {
  const response = await fetch(
    `${BASE_URL}/barcodes/${barcode}`,
    {
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    }
  );

  if (!response.ok) {
    if (response.status === 404) {
      console.log("数据库中未找到产品");
      return null;
    }
    throw new Error(`API错误: ${response.status}`);
  }

  const data = await response.json();
  return data.data;
}

// 示例用法
const product = await lookupBarcode("0049000006346");

if (product) {
  const serving = product.default_serving;
  const factor = serving.grams / 100;

  console.log(`${product.name} (${product.brand})`);
  console.log(`每${serving.description}:`);
  console.log(`  卡路里: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
  console.log(`  蛋白质: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
  console.log(`  碳水化合物: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
  console.log(`  脂肪: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}

Swift：构建自动补全搜索字段

import Foundation

class Nutrola API {
    private let apiKey: String
    private let baseURL = "https://api.nutrola.com/v1"

    init(apiKey: String) {
        self.apiKey = apiKey
    }

    func autocomplete(query: String, limit: Int = 5) async throws -> [FoodSuggestion] {
        guard query.count >= 2 else { return [] }

        var components = URLComponents(string: "\(baseURL)/foods/autocomplete")!
        components.queryItems = [
            URLQueryItem(name: "q", value: query),
            URLQueryItem(name: "limit", value: String(limit))
        ]

        var request = URLRequest(url: components.url!)
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")

        let (data, _) = try await URLSession.shared.data(for: request)
        let response = try JSONDecoder().decode(AutocompleteResponse.self, from: data)
        return response.data.suggestions
    }
}

struct FoodSuggestion: Codable {
    let id: String
    let name: String
    let brand: String?
    let category: String
}

struct AutocompleteResponse: Codable {
    let status: String
    let data: AutocompleteData
}

struct AutocompleteData: Codable {
    let suggestions: [FoodSuggestion]
}

错误处理最佳实践

API使用标准HTTP状态码：

状态码	意义	常见原因
200	成功	请求正常完成
400	错误请求	缺少必需参数或无效值
401	未授权	无效或缺失API密钥
403	禁止	API密钥缺少所需作用域
404	未找到	食品ID或条形码不在数据库中
429	速率限制	请求过多；检查速率限制头
500	服务器错误	内部错误；建议使用指数退避重试

当您收到429响应时，Retry-After头告诉您在重试之前需要等待多少秒。强烈建议在生产应用中为429和500响应实现指数退避。

数据新鲜度和更新

Nutrola的数据库持续更新。当制造商报告更改时，品牌产品条目会在48小时内刷新。政府数据库条目在新发布时每季度同步。

如果您的应用程序缓存API响应（我们建议这样做以提高性能），我们建议食品详细响应的缓存TTL为24小时，搜索结果的缓存TTL为1小时。食品详细响应中的last_verified字段告诉您该条目上次确认准确的时间。

对于企业客户，我们提供Webhook通知，当食品条目更新时，您的应用程序可以主动使缓存数据失效，而不是等待缓存TTL到期。

开始使用

注册在developer.nutrola.com — 不到一分钟
生成API密钥，并指定所需的作用域
使用上述curl示例进行第一次请求
探索交互式文档 在developer.nutrola.com/docs，您可以直接在浏览器中测试端点
加入开发者社区 在我们的Discord服务器上获取支持、功能请求，并查看其他开发者正在构建的内容

如果您有任何问题、遇到问题或想讨论企业集成，请通过api@nutrola.com与我们的开发者关系团队联系。

常见问题

Nutrola API是免费使用的吗？

是的，免费层包括每日500个请求。这适合开发、测试和小规模应用。对于流量较大的生产应用，增长层的起价为每月49美元，提供每日25,000个请求。企业计划可用于高流量用例，具有自定义限制。

API支持哪些数据格式？

API专门使用JSON进行请求和响应。所有端点接受标准查询参数用于GET请求，以及JSON请求体用于POST请求。响应编码为UTF-8，能够正确处理所有支持语言的食品名称。

API提供的营养数据准确吗？

Nutrola数据库中的每个条目都经过多层验证过程，包括政府来源验证、制造商数据交叉引用、AI驱动的统计检查和人工专家审查。我们的准确性基准为97.4%，相比之下，众包数据库的行业平均水平为70-85%。每个食品条目包括一个confidence_score字段，指示我们的确定性水平。

我可以使用API构建商业产品吗？

可以。API旨在用于商业用途。免费层可以在其速率限制内用于商业产品。增长层和企业计划包括商业使用权，对应用类型没有限制。请查看developer.nutrola.com的服务条款以获取完整细节。

API支持来自美国以外的食品吗？

是的。数据库覆盖来自47个国家的品牌产品和超过120种美食的通用食品。使用搜索端点上的country参数可以优先考虑来自特定市场的结果。条形码查找会自动将产品匹配到正确的区域配方。

如何处理数据库中不存在的食品？

如果条形码查找返回404，您可以使用产品名称进行文本搜索。如果两种方法都无法找到食品，您可以通过开发者门户提交添加请求。API合作伙伴提交的食品会优先进行验证，通常在72小时内添加。企业客户可以请求批量添加大量产品目录。

是否提供SDK或客户端库？

我们为Python（通过pip: pip install nutrola）、JavaScript/TypeScript（通过npm: npm install @nutrola/api）和Swift（通过Swift Package Manager）提供官方客户端库。这些库处理身份验证、速率限制、重试和响应解析。社区维护的库可用于Go、Ruby和PHP。

准备好改变您的营养追踪方式了吗？

加入成千上万已通过 Nutrola 改变健康之旅的用户！

Download on theApp Store

GET IT ONGoogle Play