API di ricerca per codici a barre

Cosa fa una singola ricerca

Invia GET /v1/foods/barcode/{code} con la tua chiave nell'header X-API-Key. Il codice va da GTIN-8 a GTIN-14, al massimo 20 caratteri. FoodBase prova prima una corrispondenza esatta con il codice a barre memorizzato, poi gli equivalenti con zeri di riempimento dello stesso numero, quindi un UPC-A a 12 cifre trova il record memorizzato come EAN a 13 cifre.

Per 5449000000996 il record torna con barcode 5449000000996 e id 62ea12b8-b260-c288-5c38-3a4906f5d6dd. Quell'id è stabile tra le reimportazioni, quindi salvalo come chiave esterna al posto della stringa del codice a barre.

Quando più righe del catalogo hanno lo stesso codice a barre, vince la riga più popolare e la scelta è deterministica: lo stesso codice restituisce lo stesso prodotto a ogni chiamata.

• Il barcode restituito è la forma memorizzata, non necessariamente quella che hai inviato.

Leggere il record

Il corpo 200 è lo stesso record alimentare completo che la Food Database API restituisce per id, quindi scrivi il parser una volta sola e riutilizzalo. Per 5449000000996 significa source openfoodfacts, name_default Original Taste con voci bg e fr nell'array name, nutriscore e, nova_group 4 ed ecoscore_grade not-applicable. Testi d'etichetta come serving_size_raw (1 can (330 ml)) e quantity (0kg in questo record, un errore di un contributore) tornano come digitati sulla confezione, quindi considerali un indizio e non un numero.

• categories_tags è la tassonomia leggibile da macchina (en:colas); category è lo stesso percorso come stringa di visualizzazione unita da virgole.
• allergens e traces sono null quando la fonte non ne elenca alcuno, il che non equivale a privo di allergeni.
• image_url punta a images.openfoodfacts.org e può cambiare quando i contributori aggiornano il prodotto.

Localizzazione e nutrizione

Aggiungi ?lang=bg (o en, fr, es, de, it) per riempire category_localized, category_segments_localized e allergens_localized dai dizionari di traduzione. Dove non esiste una traduzione il campo è null, non un ripiego in inglese, quindi tieni category e allergens nella tua catena di fallback. lang non tocca name né ingredients.

nutrition_summary ha sei chiavi: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g, fiber_g. Ognuna può essere null, e l'intero oggetto è null quando la fonte non ha registrato alcuna nutrizione. Per la tabella completa per 100 g, oltre 40 nutrienti dove la fonte li ha, chiama la Nutrition API con l'id che hai appena ricevuto.

Flusso dello scanner, cache e mancate corrispondenze

Con un 200, mostra la scheda a partire da name_default, brand, image_url e nutrition_summary, e conserva l'id. Con un 404 il codice non è nel catalogo: ripiega sulla Food Image Recognition API con una foto del fronte della confezione, oppure offri all'utente una ricerca testuale. Non riprovare un 404; non cambierà finché il catalogo non viene aggiornato.

Le risposte 200 portano Cache-Control: public, max-age=300, e i 404 sono memorizzabili in cache per 60 secondi. Rispettali in qualsiasi cache tra i tuoi utenti e FoodBase. Ogni risposta porta anche X-RateLimit-Second-Remaining e gli header della quota giornaliera; regola il ritmo in base a essi prima di vedere un 429.

La copertura è migliore per i prodotti della grande distribuzione europea e statunitense, perché il catalogo è costruito da Open Food Facts e USDA FoodData Central, con GS1 Bulgaria e Metro Bulgaria in aggiunta. Le linee a marchio del distributore e i prodotti molto recenti sono i casi mancanti più comuni.