Как да разбираш хранителните данни

Източници на данни

Нашата база данни обединява два големи отворени източника в единен, нормализиран формат:

Open Food Facts (4,1 млн. продукта) — глобална база данни, поддържана от общността, със силно покритие в Европа. Продуктите включват баркодове, имена и съставки на много езици, Nutri-Score, NOVA класификация, данни за алергени и снимки. Лиценз ODbL.

USDA FoodData Central (2,0 млн. продукта) — обширната база данни за състава на храните на Министерството на земеделието на САЩ. Включва лабораторно проверени хранителни стойности за маркови продукти, foundation foods и по-стари референтни храни. Обществено достояние.

Заедно това са 6,1 милиона уникални хранителни продукта — повече, отколкото предлага който и да е източник поотделно.

Как обединяваме данните

Когато един продукт съществува и в двете бази данни (съпоставен по баркод), даваме приоритет на хранителните стойности от USDA (лабораторно проверени) и ги допълваме с метаданни от Open Food Facts (снимки, алергени, Nutri-Score, имена на много езици). Така получаваш най-доброто от двата свята: точни хранителни данни с богати метаданни за продукта.

Нива на хранителните вещества

Не за всеки продукт е измерено всяко хранително вещество. Затова ги подреждаме в нива според покритието на данните:

Ниво 1: Основни макроси (97%+ покритие)

Налични за почти всеки продукт в базата ни:

Хранително вещество	Поле	Мерна единица
Енергия	`energy_kcal`, `energy_kj`	kcal, kJ
Белтъчини	`proteins_g`	g
Въглехидрати	`carbs_g`	g
Мазнини	`fat_g`	g
Захари	`sugars_g`	g
Наситени мазнини	`saturated_fat_g`	g
Натрий	`sodium_mg`	mg
Сол	`salt_g`	g
Фибри	`fiber_g`	g

Ниво 2: Често срещани хранителни вещества

Налични за голяма част от продуктите — особено за лабораторно проверените записи — но далеч не за всички. Покритието варира според веществото и продължава да се подобрява с обновяването на източниците:

Хранително вещество	Поле
Холестерол	`cholesterol_mg`
Трансмазнини	`trans_fat_g`
Калций	`calcium_mg`
Желязо	`iron_mg`
Витамин C	`vitamin_c_mg`
Калий	`potassium_mg`
Витамин A	`vitamin_a_iu`
Добавени захари	`added_sugars_g`

Ниво 3: Разширени хранителни вещества

Налични за по-малка част от продуктите, главно за лабораторно анализирани храни:

Витамин D, магнезий, цинк, фосфор, витамини от група B (B1, B2, B6, B9, B12), ниацин, пантотенова киселина, манган, мед, селен, йод, алкохол, нишесте, полиоли, мононенаситени мазнини, полиненаситени мазнини, омега-3 и омега-6 мастни киселини.

Работа с данните

Всички стойности са на 100 г

Всяка хранителна стойност в нашия API е нормализирана на 100 г продукт. За да изчислиш стойностите на порция, умножи по размера на порцията:

const perServing = (valuePer100g, servingGrams) => {
  return Math.round(valuePer100g * (servingGrams / 100) * 10) / 10;
};

// Example: 42 kcal per 100g, 330ml can
perServing(42, 330); // → 138.6 kcal

Работа с null стойности

API-то връща null за хранителни вещества, които не са налични за даден продукт. Приложението ти трябва да се справя спокойно с липсващи стойности — не приемай, че всеки продукт има всяко поле.

const calories = food.nutrition_summary?.energy_kcal ?? "N/A";

Поддръжка на много езици

Продуктите от Open Food Facts съдържат имена и съставки на няколко езика. Полето name връща масив от обекти {lang, text}:

[
  {"lang": "main", "text": "Coca-Cola"},
  {"lang": "fr", "text": "Coca-Cola en canette"},
  {"lang": "de", "text": "Coca-Cola"}
]

Полето name_default винаги съдържа текста на основния език — за бърз достъп, без да парсваш масива.

Качество на данните

В нашия pipeline за данни прилагаме няколко филтъра за качество:

Физически горни граници на хранителните стойности, за да отсеем некоректни данни (например белтъчините не могат да надхвърлят 100 г на 100 г)
Нормализиране на мерните единици за еднакви единици във всички източници (g, mg, mcg, IU)
Премахване на дубликати по баркод, като при припокриващи се продукти лабораторно проверените стойности имат приоритет
Оценка на пълнотата, за да можеш да филтрираш по качество на данните, когато ти трябва

Искаш да разгледаш данните, преди да пишеш код? Всеки продукт в каталога има публична страница в Product Explorer, която показва точно полетата, които връща API-то — таблица с хранителни стойности, съставки, алергени, оценки и всичко останало.