API за търсене по баркод

Какво прави едно търсене

Изпрати GET /v1/foods/barcode/{code} с ключа си в заглавката X-API-Key. Кодът е от GTIN-8 до GTIN-14, най-много 20 символа. FoodBase първо опитва точно съвпадение със съхранения баркод, после еквивалентите му с водещи нули, така че 12-цифров UPC-A намира записа, съхранен като 13-цифров EAN.

За 5449000000996 записът се връща с barcode 5449000000996 и id 62ea12b8-b260-c288-5c38-3a4906f5d6dd. Това id е стабилно при повторен внос, затова го пази като външен ключ вместо низа на баркода.

Когато няколко реда в каталога носят един и същ баркод, печели най-популярният и изборът е детерминиран: един и същ код връща един и същ продукт при всяко извикване.

• Върнатият barcode е съхранената форма, не непременно формата, която си изпратил.

Четене на записа

Тялото на 200 е същият пълен запис за храна, който API за база данни с храни връща по id, така че го парсвай веднъж и преизползвай парсера. За 5449000000996 това означава source openfoodfacts, name_default Original Taste с вписвания bg и fr в масива name, nutriscore e, nova_group 4 и ecoscore_grade not-applicable. Текст от етикета като serving_size_raw (1 can (330 ml)) и quantity (0kg в този запис — грешка на контрибутор) се връща, както е въведен на опаковката, затова го третирай като подсказка, а не като число.

• categories_tags е машинночетимата таксономия (en:colas); category е същият път като низ със запетаи за показване.
• allergens и traces са null, когато източникът не изброява такива, което не е същото като без алергени.
• image_url сочи към images.openfoodfacts.org и може да се промени, когато контрибутори обновят продукта.

Локализация и хранителни стойности

Добави ?lang=bg (или en, fr, es, de, it), за да се попълнят category_localized, category_segments_localized и allergens_localized от речниците за превод. Където няма превод, полето е null, а не английски вариант, затова дръж category и allergens във веригата си от резервни стойности. lang не засяга name или ingredients.

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

Поток със скенер, кеширане и пропуски

При 200 визуализирай картата от name_default, brand, image_url и nutrition_summary и запази id. При 404 кодът не е в каталога: премини към API за разпознаване на храни от снимка със снимка на предната страна на опаковката или дай на потребителя текстово търсене. Не повтаряй 404; няма да се промени, докато каталогът не бъде обновен.

Отговорите 200 носят Cache-Control: public, max-age=300, а 404 могат да се кешират 60 секунди. Спазвай ги във всеки кеш между потребителите ти и FoodBase. Всеки отговор носи и X-RateLimit-Second-Remaining и заглавките за дневната квота; ограничавай скоростта по тях, преди да видиш 429.

Покритието е най-добро за европейски и американски търговски продукти, защото каталогът е изграден от Open Food Facts и USDA FoodData Central, с GS1 България и Metro България отгоре. Най-честите пропуски са продукти с търговска марка на веригата (private label) и много нови продукти.