API за търсене на храни

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

Търсенето е една GET заявка с текста в q. Думите се сравняват едновременно с името на продукта и с марката, така че q=olympus milk намира продукти, чиито имена никога не казват Olympus, а последната дума се третира като префикс, така че milk olym съвпада още докато потребителят пише. Трябва да съвпаднат всички думи; няма OR. q трябва да е от 1 до 200 символа; липсващо или празно q се отхвърля още преди да започне търсене, затова пази празното поле за търсене от твоя страна.

Продуктите с име точно като въведеното идват първи, така че banana показва бананите преди бананови кисели млека, а greek yogurt — обикновените гръцки кисели млека. След тях резултатите са подредени по релевантност, а когато два продукта съвпадат еднакво добре, по-популярният е по-напред. Търсене по марка като pringles пропуска стъпката с точно име и остава подредено по популярност, а добавянето на втора дума (марка, вкус) е най-бързият начин да изведеш конкретен продукт по-нагоре.

Имената на категориите са резервен вариант, не част от основното съвпадане: само когато търсенето по име и марка не намери нищо, API търси продукти, чиято категория съдържа думите, на какъвто и език да е записана. Именно затова заявка като Seeds & Related Snacks или Fruits tropicaux връща списък, подреден по популярност, вместо празен масив.

• Редът не е нито азбучен, нито по id. Не пренареждай масива data от страна на клиента.
• Ако въведеното е GTIN само от цифри, изпрати го към API за търсене по баркод: то разрешава варианти с водещи нули (0000080042556 намира 80042556), което текстовото търсене не прави.

Как да четеш ред от резултатите

Всеки елемент в data е FoodListItem — по-лека форма от пълния запис: id, barcode, source, name_default, brand, category, image_url, nutriscore и nova_group, плюс name_localized (винаги налично) и category_localized, когато е подаден lang, различен от английски. Тук няма хранителни вещества; списъкът е направен за визуализиране на редове, не за изчисления.

Няколко полета могат да са null и примерът го показва. Бонбоните „Banana land“ на Roshen (4f995c13-c0df-bfcc-b6ec-449d312def75) имат image_url null и nova_group null; brand и barcode също могат да са null. Стойности на nutriscore извън a до e, като „n“ и „u“ в примера, означават, че не е изчислена оценка, затова показвай „без оценка“ вместо суровата буква.

category е пълният път на категорията от Open Food Facts, разделен със запетаи от общо към конкретно („...,Fruits tropicaux,Bananes“ за бананите на Bio Village). Показвай последния сегмент като етикет или първия за груба група и премахвай езиковите префикси като pt: преди показване. image_url е снимка от контрибутор в images.openfoodfacts.org, затова подготви заместваща картинка за случая с null.

Странициране, total и стабилни id-та

limit е от 1 до 100 (по подразбиране 20), а offset — от 0 до 10000. total е ограничен брой: API спира да брои при 1000 съвпадения, така че total 1000 в примера за q=banana с limit=3 означава поне 1000. Показвай го като „1000+“ и не изчислявай номер на последна страница от него.

Странирай, като добавяш limit към offset, докато data върне по-малко от limit елемента. Тъй като offset стига най-много до 10000, заявка с повече съвпадения от това има нужда от по-тесен q, а не от по-дълбока страница.

• Id-тата са стабилни при повторен внос във FoodBase, така че запази id от ред на търсене и го разрешавай по-късно с API за база данни с храни, без да търсиш отново.
• Подреждането се изчислява при всяка заявка и популярността може да се променя, затова offset не е траен курсор. Пази id-та, не позиции на страници.

Търсене на друг език

lang е en по подразбиране. Всеки език търси във вписването на този език в масива с имена на продукта, където доброволец или AI преводът на FoodBase е предоставил такова, и се връща към name_default — името, както е отпечатано на етикета — за продукти без такова вписване; марката винаги участва в съвпадението. Така lang=bg достига до всеки продукт, но предпочита български имена, където съществуват, а етикет на кирилица се намира при всеки lang.

Подаденият lang оформя и изхода. name_localized съдържа преведеното име: примерът, поискан с lang=en, превръща „Puré de plátano y fresa“ в „Banana and Strawberry Puree“ и се връща към name_default, когато няма какво да се превежда, както показва „Banana land“. Показвай name_localized, когато не е null, иначе name_default. category_localized не е задължително поле и липсва в примера, затова го чети защитно.

Автодовършване и преминаване към пълните записи

Търсенето е правилната крайна точка за поле с автодовършване. Забави натисканията на клавиши (debounce), искай limit=8 до 10 и отменяй заявката в процес, когато потребителят пише отново, за да не може бавен по-стар отговор да презапише по-нов. Всяко натискане на клавиш, стигнало до API, е една заявка от дневната ти квота, така че debounce е толкова контрол на разходите, колкото и UX детайл.

Когато потребителят избере ред, извикай API за база данни с храни с id за пълния запис, или API за хранителни стойности, когато ти трябва само таблицата с хранителни вещества на 100 g. Едно търсене плюс една заявка за детайли е по-евтино от теглене на пълни записи за всяко предложение.

Заснетият отговор на търсенето няма заглавка Cache-Control, за разлика от записите за храни, които могат да се кешират 300 секунди. Кеширай резултатите от търсенето сам, с ключ точните q, lang, limit и offset; едни и същи кратки префикси се повтарят непрекъснато в поле с автодовършване. X-RateLimit-Second-Remaining показва колко burst е останал, а при 429 заглавката Retry-After казва колко секунди да изчакаш.