API за хранителни стойности

Една заявка, пет групи, на 100 g

GET /v1/foods/{id}/nutrients приема UUID на храната в пътя и нищо друго: няма параметри на заявката, няма тяло, няма lang. Id е същото, което връщат всички други крайни точки, така че резултат от API за търсене на храни или API за търсене по баркод става пълна разбивка с още едно извикване. Id-тата са детерминирани при повторен внос, така че можеш да ги пазиш и да продължиш да викаш същия URL.

Отговорът е плосък обект с food_id плюс пет фиксирани групи: macros, fats, minerals, vitamins и other. Всеки ключ винаги присъства и всяка стойност е число или null. Преброяването на ключовете в текущата схема дава 41 полета за хранителни вещества, откъдето идва числото „над 40“. Мерните единици са в името на ключа (energy_kcal, sodium_mg, selenium_mcg, vitamin_a_iu), така че не ти трябва отделна таблица с единици.

Всички стойности са на 100 g от продукта, както се продава. За да покажеш порция, умножи по грамовете, разделени на 100. serving_size_raw в записа на храната е текст от етикета (за примерния запис на Coca-Cola е „1 can (330 ml)“), така че преобразуването от този текст в грамове е твоя работа.

• macros (10 ключа) покрива енергия в kcal и kJ, протеини, въглехидрати, мазнини, захари, фибри, алкохол, скорбяла и полиоли; fats (7) добавя наситени, транс-, мононаситени и полиненаситени мазнини, omega3, omega6 и cholesterol_mg
• minerals (12) върви от sodium_mg и salt_g до selenium_mcg и iodine_mcg; vitamins (11) отчита A и D в IU, B9 и B12 в mcg, останалите в mg; other съдържа added_sugars_g

Как да четеш правилно null и нули

Примерният отговор за храна 62ea12b8-b260-c288-5c38-3a4906f5d6dd показва типичния модел на Open Food Facts: energy_kcal 42, energy_kj 180.2, carbs_g 10.6, sugars_g 10.6, added_sugars_g 5.3, изрични нули за proteins_g, fat_g, saturated_fat_g, sodium_mg и salt_g и null за всичко останало, от fiber_g до цялата група vitamins.

Третирай двете състояния по различен начин. 0 е стойност, отчетена от източника; null означава, че хранителното вещество не е на етикета или не е в източника. Никога не превръщай null в 0, преди да сумираш дневния прием, иначе хранене от частично етикетирани продукти тихо ще отчете по-малко витамини и минерали. Показвай тире или „не е отчетено“.

Покритието следва произхода. Редовете със source usda_foundation или usda_sr_legacy са лабораторни анализи на USDA и попълват групите за витамини и минерали, така че повечето ключове са числа. Редовете със source usda (USDA Branded Foods) и редовете от Open Food Facts са преписани от опаковката, така че са надеждни за задължителните хранителни вещества на етикета и често са null извън тях. Полето source в записа на храната ти казва в кой случай си, преди да визуализираш таблицата.

• Показвай null като неизвестно, не като нула; агрегирай само ключове, които са различни от null във всеки продукт на храненето.
• sodium_mg и salt_g съществуват и двата, защото етикетите се различават по региони; използвай този, който аудиторията ти очаква, и се връщай към другия.

Кога наистина ти трябва това извикване

Всеки запис за храна от API за база данни с храни и всяко съвпадение по баркод вече включва nutrition_summary с шест основни стойности: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g и fiber_g. Редовете от търсенето са по-леки и го нямат. За резултат от скенер, карта с детайли или бързо записване на калории този обект обикновено е достатъчен и не струва разбивка на хранителни вещества.

Запази /nutrients за екрана с детайли или за момента, в който потребителят попита за натрий, наситени мазнини, холестерол или конкретен витамин. Търси или сканирай, покажи обобщението, дръпни разбивката при докосване. В плана Free това е и начинът да останеш в рамките на лимита от 25 на ден, докато разработваш.

Заснетите заглавки на отговора не носят Cache-Control, така че кеширането е твоя работа. Id-тата са стабилни и стойностите се променят само когато продуктът бъде внесен повторно, така че кеш с ключ food_id и срок от часове или дни е безопасен.

Лимитът на плана Free, заглавка по заглавка

В плана Free всяка успешна разбивка намалява отделен дневен брояч от 25, отчитан във всеки отговор като X-RateLimit-Nutrients-Limit, X-RateLimit-Nutrients-Remaining и X-RateLimit-Nutrients-Reset. Чети Remaining преди серия от заявки за детайли и можеш да преминеш към nutrition_summary, вместо да се удариш в стената по средата на сесия.

При нула крайната точка връща 429 с error „Nutrients daily allowance exceeded“, upgrade_url в тялото и Retry-After със секундите до полунощ UTC. Отхвърлено извикване не изразходва нито разбивка, нито дневна заявка и не измества нулирането. Платените планове нямат такъв брояч; техните извиквания за хранителни вещества са ограничени само от дневната квота заявки на плана (споделена между всички ключове на акаунта) и от лимита за секунда на ключ.

Ако си на Starter или по-горе и обработваш голям каталог, първо вземи базовите записи през API за групово търсене на храни и викай /nutrients само за id-тата, за които обобщението не е достатъчно.