API данных о питании Nutrola: как разработчики могут получить доступ к нашей базе данных продуктов

Разрабатываете приложение для здоровья, фитнеса или питания? Одна из самых сложных проблем, с которой вы столкнётесь, — это данные о питании. Вам нужна точная информация о калориях и макронутриентах для тысяч продуктов, она должна охватывать международные товары и оставаться актуальной по мере того, как производители изменяют рецептуры.

Большинство разработчиков начинают с извлечения данных из открытых государственных баз данных, таких как USDA FoodData Central. Это даёт вам основу, но не покрывает брендированные продукты из 47 стран, блюда ресторанов или тысячи региональных продуктов, которые реальные пользователи потребляют каждый день. Заполнение этих пробелов самостоятельно означает годы работы по курированию данных.

API данных о питании Nutrola предоставляет разработчикам доступ к той же верифицированной базе данных продуктов, которая используется в нашем приложении — более 3 миллионов записей, охватывающих сырые ингредиенты, брендированные продукты, блюда ресторанов и составные рецепты. Каждая запись проверена в рамках нашего многоуровневого процесса контроля качества — той же системы, которой доверяют более 2 миллионов пользователей.

Это руководство охватывает всё, что вам нужно знать для начала работы с нашим API: архитектуру, аутентификацию, эндпоинты, лимиты запросов и примеры кода из реальной практики.

Обзор API

API данных о питании Nutrola — это RESTful JSON API. Вы отправляете HTTP-запросы и получаете JSON-ответы. SDK не требуются, хотя мы предоставляем клиентские библиотеки для Python, JavaScript и Swift для удобства.

Базовый URL

https://api.nutrola.com/v1

Все эндпоинты работают через HTTPS. Обычные HTTP-запросы отклоняются.

Основные возможности

Возможность	Описание
Поиск продуктов	Полнотекстовый поиск по 3M+ записям о продуктах с фильтрацией по категории, бренду и стране
Поиск по штрихкоду	Получение данных о питании по 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": "No food entry matches the provided ID.",
    "request_id": "req_xyz789"
  }
}

Аутентификация

Все запросы к API требуют API-ключ, передаваемый в заголовке Authorization.

Получение API-ключа

1. Создайте аккаунт разработчика на developer.nutrola.com
2. Перейдите в раздел API-ключей в вашей панели управления
3. Сгенерируйте новый ключ и укажите необходимые области доступа
4. Сохраните ключ в безопасном месте — он будет показан только один раз

Использование 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	Да	Поисковый запрос (например, "grilled chicken breast")
category	string	Нет	Фильтр по категории продукта (например, "dairy", "vegetables")
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": "Greek Yogurt, Plain, Nonfat",
        "brand": null,
        "category": "dairy",
        "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 container (170g)",
          "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": "Greek Yogurt, Plain, Nonfat",
    "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 container (170g)", "grams": 170 },
      { "description": "1 cup (245g)", "grams": 245 },
      { "description": "1 tbsp (15g)", "grams": 15 },
      { "description": "100g", "grams": 100 }
    ],
    "allergens": ["milk"],
    "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": "Overnight Oats",
  "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": "pinch of salt" }
  ]
}

Вы также можете отправить ингредиенты в виде текста для автоматического разбора:

{
  "name": "Overnight Oats",
  "servings": 2,
  "ingredients_text": "160g rolled oats, 400ml whole milk, 60g peanut butter, pinch of salt"
}

Ответ:

{
  "status": "success",
  "data": {
    "name": "Overnight Oats",
    "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": "160g rolled oats", "matched_food": "food_3k8m2n", "confidence": 0.97 },
      { "input": "400ml whole milk", "matched_food": "food_9p4q7r", "confidence": 0.99 },
      { "input": "60g peanut butter", "matched_food": "food_1a5b8c", "confidence": 0.96 },
      { "input": "pinch of salt", "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

Тариф Growth

Для рабочих приложений с умеренным трафиком:

Ограничение	Значение
Запросов в день	25 000
Запросов в минуту	300
Результатов поиска продуктов на запрос	50
Анализов рецептов в день	500
Поисков по штрихкоду в день	5 000
Цена	$49/месяц

Тариф Enterprise

Для высоконагруженных приложений, решений white-label и индивидуальных требований:

Параметр	Подробности
Запросов в день	Индивидуально (обычно 100K+)
Лимиты запросов	Индивидуально
Выделенная поддержка	Включена
SLA	Гарантия бесперебойной работы 99,9%
Пользовательский экспорт данных	Доступен
Уведомления через webhook	Доступны при обновлении данных
Цена	Свяжитесь с отделом продаж

Информация о лимитах запросов включается в каждый ответ API через объект meta и в HTTP-заголовки ответа (X-RateLimit-Remaining, X-RateLimit-Reset).

Реальные сценарии использования

Фитнес-приложения и приложения для тренировок

Если вы разрабатываете фитнес-приложение и хотите добавить отслеживание питания без создания базы данных продуктов с нуля, API Nutrola — самый быстрый путь. Используйте эндпоинты поиска продуктов и штрихкодов, чтобы пользователи могли записывать приёмы пищи, и эндпоинт анализа рецептов для пользовательских записей о блюдах.

Платформы планирования питания

Приложениям для планирования питания нужны точные данные о питательной ценности для создания планов, соответствующих определённым целям по макронутриентам. Детальная разбивка по нутриентам (70+ нутриентов) в API позволяет точно оптимизировать планы питания — не только калории и макронутриенты, но и микроэлементы, аллергены и совместимость с диетическими ограничениями.

Здравоохранение и телемедицина

Медицинские платформы, отслеживающие питание пациентов, могут интегрироваться с 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": "chicken breast grilled", "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"Calories: {nutrition['calories']}")
print(f"Protein: {nutrition['protein']}g")
print(f"Carbs: {nutrition['carbohydrates']}g")
print(f"Fat: {nutrition['fat']}g")
print(f"Serving sizes: {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("Product not found in database");
      return null;
    }
    throw new Error(`API error: ${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(`Per ${serving.description}:`);
  console.log(`  Calories: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
  console.log(`  Protein: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
  console.log(`  Carbs: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
  console.log(`  Fat: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}

Swift: создание поля поиска с автодополнением

import Foundation

class NutrolaAPI {
    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 указывает, сколько секунд нужно подождать перед повторной попыткой. Настоятельно рекомендуется реализовать экспоненциальную задержку (exponential backoff) для ответов 429 и 500 в рабочих приложениях.

Актуальность данных и обновления

База данных Nutrola обновляется непрерывно. Записи о брендированных продуктах обновляются, когда производители сообщают об изменениях, обычно в течение 48 часов. Записи из государственных баз данных синхронизируются ежеквартально при выходе новых версий.

Если ваше приложение кеширует ответы API (что мы рекомендуем для производительности), мы предлагаем TTL кеша 24 часа для детальных ответов о продуктах и 1 час для результатов поиска. Поле last_verified в детальных ответах о продуктах указывает, когда запись была в последний раз подтверждена как точная.

Для корпоративных клиентов мы предлагаем уведомления через webhook при обновлении записей о продуктах, чтобы ваше приложение могло проактивно инвалидировать кешированные данные, не дожидаясь истечения TTL кеша.

Начало работы

1. Зарегистрируйтесь на developer.nutrola.com — это займёт менее минуты
2. Сгенерируйте API-ключ с нужными вам областями доступа
3. Сделайте первый запрос, используя примеры curl выше
4. Изучите интерактивную документацию на developer.nutrola.com/docs, где можно тестировать эндпоинты прямо в браузере
5. Присоединяйтесь к сообществу разработчиков на нашем Discord-сервере для получения поддержки, отправки запросов на новые функции и знакомства с тем, что создают другие разработчики

Если у вас есть вопросы, возникли проблемы или вы хотите обсудить корпоративную интеграцию, свяжитесь с нашей командой по работе с разработчиками по адресу api@nutrola.com.

Часто задаваемые вопросы

API Nutrola бесплатный?

Да, существует бесплатный тариф, включающий 500 запросов в день. Этого достаточно для разработки, тестирования и небольших приложений. Для рабочих приложений с более высоким трафиком тариф Growth начинается от $49 в месяц с 25 000 запросов в день. Корпоративные планы с индивидуальными лимитами доступны для высоконагруженных сценариев.

Какие форматы данных поддерживает API?

API использует исключительно JSON как для запросов, так и для ответов. Все эндпоинты принимают стандартные параметры запроса для GET-запросов и JSON-тела для POST-запросов. Кодировка ответов — UTF-8, что корректно обрабатывает названия продуктов на всех поддерживаемых языках.

Насколько точны данные о питании, предоставляемые API?

Каждая запись в базе данных Nutrola проходит многоуровневый процесс верификации, включающий проверку по государственным источникам, перекрёстную сверку с данными производителей, статистическую проверку на основе ИИ и экспертный обзор. Наш эталон точности составляет 97,4% по сравнению с лабораторным анализом, тогда как среднеотраслевой показатель для краудсорсинговых баз данных составляет 70-85%. Каждая запись о продукте включает поле confidence_score, указывающее уровень нашей уверенности.

Могу ли я использовать API для создания коммерческого продукта?

Да. API разработан для коммерческого использования. Бесплатный тариф можно использовать для коммерческих продуктов в рамках его лимитов. Тарифы Growth и Enterprise включают права на коммерческое использование без ограничений по типу приложения. Ознакомьтесь с условиями использования на 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.