Nutrola Nutrition Data API: Як розробники можуть отримати доступ до нашої бази даних продуктів

Розробляєте додаток у сфері здоров'я, фітнесу або харчування? Однією з найскладніших проблем, з якими ви зіткнетеся, є дані про харчування. Вам потрібна точна інформація про калорії та макроелементи для тисяч продуктів, яка охоплює міжнародні товари та залишається актуальною, оскільки виробники змінюють свої рецептури.

Більшість розробників починають з отримання даних з відкритих державних баз даних, таких як USDA FoodData Central. Це дає вам основу, але не охоплює брендові продукти з 47 країн, страви з ресторанів або тисячі регіональних продуктів, які справжні користувачі споживають щодня. Заповнення цих прогалин самостійно означає роки роботи з курацією даних.

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

Цей посібник охоплює все, що вам потрібно знати, щоб почати працювати з нашим API: архітектура, аутентифікація, кінцеві точки, обмеження запитів та реальні приклади коду.

Огляд API

Nutrola Nutrition Data API — це 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": "Не знайдено жодного продукту, що відповідає наданому ID.",
    "request_id": "req_xyz789"
  }
}

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

Усі запити до API вимагають API-ключ, який передається в заголовку Authorization.

Отримання API-ключа

1. Створіть обліковий запис розробника на developer.nutrola.com
2. Перейдіть до розділу API Keys у вашій панелі управління
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	Так	Пошуковий запит (наприклад, "грила куряча грудка")
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 контейнер (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": "Грецький йогурт, простий, нежирний",
    "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 контейнер (170g)", "grams": 170 },
      { "description": "1 склянка (245g)", "grams": 245 },
      { "description": "1 ст. ложка (15g)", "grams": 15 },
      { "description": "100g", "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": "160g вівсяних пластівців, 400ml цільного молока, 60g арахісового масла, щіпка солі"
}

Відповідь:

{
  "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": "160g вівсяних пластівців", "matched_food": "food_3k8m2n", "confidence": 0.97 },
      { "input": "400ml цільного молока", "matched_food": "food_9p4q7r", "confidence": 0.99 },
      { "input": "60g арахісового масла", "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%
Індивідуальні експорти даних	Доступні
Сповіщення через вебхуки	Доступні для оновлень даних
Ціна	Зв'яжіться з відділом продажу

Інформація про обмеження запитів включена в кожну відповідь API через об'єкт meta та у заголовках HTTP-відповіді (X-RateLimit-Remaining, X-RateLimit-Reset).

Реальні випадки використання

Додатки для фітнесу та тренувань

Якщо ви розробляєте фітнес-додаток і хочете додати відстеження харчування без створення бази даних продуктів з нуля, API Nutrola — найшвидший шлях. Використовуйте кінцеві точки пошуку продуктів та штрих-кодів, щоб дозволити користувачам реєструвати прийоми їжі, а кінцеву точку аналізу рецептів для налаштування введення страв.

Платформи для планування харчування

Додатки для планування харчування потребують точної інформації про харчування, щоб генерувати плани, які досягають конкретних макроцілей. Детальний розподіл поживних речовин 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 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 повідомляє, скільки секунд потрібно почекати перед повтором. Рекомендується реалізувати експоненціальну затримку для відповідей 429 та 500 у виробничих додатках.

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

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

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

Для корпоративних клієнтів ми пропонуємо сповіщення через вебхуки, коли записи продуктів оновлюються, щоб ваш додаток міг проактивно анулювати кешовані дані, а не чекати закінчення TTL кешу.

Як почати

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

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

Часті запитання

Чи безкоштовний Nutrola API?

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

Які формати даних підтримує API?

API використовує виключно JSON для запитів та відповідей. Усі кінцеві точки приймають стандартні параметри запиту для GET-запитів та JSON-тіла запиту для POST-запитів. Кодування відповіді — UTF-8, що правильно обробляє назви продуктів у всіх підтримуваних мовах.

Наскільки точні дані про харчування, що надаються API?

Кожен запис у базі даних Nutrola проходить багаторівневий процес перевірки, включаючи валідацію з державних джерел, перехресну перевірку даних виробників, статистичну перевірку на основі штучного інтелекту та експертний огляд. Наша точність становить 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.