API di ricerca alimenti

Cosa fa una singola richiesta di ricerca

Una ricerca è una singola GET con il testo in q. Le parole vengono confrontate insieme con il nome del prodotto e con la marca, quindi q=olympus milk trova prodotti il cui nome non dice mai Olympus, e l'ultima parola è trattata come prefisso, così milk olym trova già qualcosa mentre l'utente sta ancora scrivendo. Devono corrispondere tutte le parole; non esiste l'OR. q deve essere lungo da 1 a 200 caratteri; una q mancante o vuota viene rifiutata prima che parta qualsiasi ricerca, quindi gestisci tu il caso della casella di ricerca vuota.

I prodotti che si chiamano esattamente come hai digitato vengono per primi, quindi banana elenca le banane prima degli yogurt alla banana e greek yogurt elenca gli yogurt greci naturali. Dopo di loro i risultati sono ordinati per rilevanza e, a parità di corrispondenza, viene prima il prodotto più popolare. Una query di marca come pringles salta il passaggio del nome esatto e resta in ordine di popolarità; aggiungere una seconda parola (una marca, un gusto) è il modo più rapido per far salire un prodotto specifico.

I nomi di categoria sono un ripiego, non parte della corrispondenza principale: solo quando la ricerca su nome e marca non trova nulla l'API cerca i prodotti la cui categoria contiene le parole, nella lingua in cui la categoria è memorizzata. È questo che fa restituire una lista (ordinata per popolarità) a una query come Seeds & Related Snacks o Fruits tropicaux, invece di un array vuoto.

• L'ordine non è né alfabetico né per id. Non riordinare l'array data lato client.
• Se l'input è un GTIN di sole cifre, invialo alla Barcode Lookup API: risolve le varianti con zeri di riempimento (0000080042556 trova 80042556), cosa che una ricerca testuale non fa.

Leggere una riga di risultato

Ogni elemento di data è un FoodListItem, una forma più leggera del record completo: id, barcode, source, name_default, brand, category, image_url, nutriscore e nova_group, più name_localized (sempre presente) e category_localized quando passi una lang diversa dall'inglese. Qui non ci sono nutrienti; l'elenco è fatto per mostrare righe, non per fare calcoli.

Diversi campi possono essere null, e l'esempio lo mostra. La caramella Roshen “Banana land” (4f995c13-c0df-bfcc-b6ec-449d312def75) ha image_url null e nova_group null; anche brand e barcode possono essere null. I valori di nutriscore diversi da a–e, come la “n” e la “u” dell'esempio, significano che non è stato calcolato alcun voto: mostrali come “non classificato” invece della lettera grezza.

category è il percorso completo delle categorie di Open Food Facts, separato da virgole dal generale allo specifico (“...,Fruits tropicaux,Bananes” per le banane Bio Village). Mostra l'ultimo segmento come etichetta, oppure il primo per un raggruppamento grossolano, e rimuovi prefissi di lingua come pt: prima di visualizzarlo. image_url è una foto di un contributore su images.openfoodfacts.org, quindi prevedi un segnaposto per il caso null.

Paginazione, total e id stabili

limit va da 1 a 100 (predefinito 20) e offset da 0 a 10000. total è un conteggio limitato: l'API smette di contare a 1.000 corrispondenze, quindi il total di 1000 dell'esempio per q=banana con limit=3 significa almeno 1.000. Mostralo come “1.000+” e non calcolare un numero di ultima pagina a partire da esso.

Pagina sommando limit a offset finché data non restituisce meno di limit elementi. Poiché offset arriva al massimo a 10000, una query con più corrispondenze di così richiede una q più stretta, non una pagina più profonda.

• Gli id sono stabili tra le reimportazioni di FoodBase: salva l'id di una riga di ricerca e risolvilo più tardi con la Food Database API senza cercare di nuovo.
• Il ranking è calcolato a ogni richiesta e la popolarità può cambiare, quindi un offset non è un cursore duraturo. Conserva gli id, non le posizioni di pagina.

Cercare in un'altra lingua

lang è en per impostazione predefinita. Ogni lingua cerca nella voce di quella lingua dell'array dei nomi del prodotto, dove un volontario o la traduzione IA di FoodBase l'ha fornita, e ripiega su name_default, il nome così com'è stampato sull'etichetta, per i prodotti che non hanno quella voce; la marca fa sempre parte della corrispondenza. Quindi lang=bg raggiunge ogni prodotto ma preferisce i nomi bulgari dove esistono, e un'etichetta in cirillico si trova con qualsiasi lang.

La lang che passi plasma anche l'output. name_localized contiene il nome tradotto: l'esempio, richiesto con lang=en, trasforma “Puré de plátano y fresa” in “Banana and Strawberry Puree” e ripiega su name_default quando non c'è nulla da tradurre, come mostra “Banana land”. Mostra name_localized quando non è null e name_default altrimenti. category_localized non è un campo obbligatorio e non compare nell'esempio, quindi leggilo in modo difensivo.

Autocompletamento e passaggio ai record completi

La ricerca è l'endpoint giusto per una casella con suggerimenti in tempo reale. Applica il debounce ai tasti, richiedi limit=8 o 10 e annulla la richiesta in corso quando l'utente digita di nuovo, così una risposta lenta precedente non può sovrascriverne una più recente. Ogni tasto che arriva all'API è una richiesta contro la tua quota giornaliera, quindi il debounce è tanto un controllo dei costi quanto un dettaglio di UX.

Quando l'utente sceglie una riga, chiama la Food Database API con l'id per il record completo, oppure la Nutrition API quando ti serve solo la tabella dei nutrienti per 100 g. Una ricerca più una richiesta di dettaglio costa meno che recuperare i record completi per ogni suggerimento.

La risposta di ricerca catturata non ha alcun header Cache-Control, a differenza dei record alimentari, che sono memorizzabili in cache per 300 secondi. Metti in cache i risultati di ricerca da solo, con chiave sull'esatta combinazione di q, lang, limit e offset; in una casella con suggerimenti gli stessi brevi prefissi ricorrono continuamente. X-RateLimit-Second-Remaining mostra quanto burst resta e, su un 429, l'header Retry-After indica quanti secondi attendere.