API del database alimentare

Cosa fa una singola richiesta

GET /v1/foods/{id} prende l'UUID ottenuto da una ricerca o da una ricerca per codice a barre e restituisce l'intero record normalizzato. Non c'è selezione dei campi né paginazione: il record per 62ea12b8-b260-c288-5c38-3a4906f5d6dd (codice a barre 5449000000996, source openfoodfacts) torna con ogni chiave dello schema 200, e tutto ciò che manca alla fonte è null, non omesso.

Autenticati con l'header X-API-Key. L'unico input facoltativo è ?lang=, uno tra en, fr, es, de, it o bg. Aggiunge category_localized, category_segments_localized e allergens_localized e lascia intatte tutte le altre chiavi, quindi aggiungere lang più avanti non rompe mai un parser esistente. Ogni risposta porta anche un header X-Request-Id da citare nelle richieste di supporto.

Nomi, ingredienti e voce principale

name e ingredients sono array di {lang, text}. La prima voce ha lang main e rispecchia name_default e ingredients_default; product_lang ti dice quale lingua reale sia. Nel record Coca-Cola il nome principale è Original Taste, la voce fr dice Coca-Cola en canette e la voce bg dice Кока-Кола. Scegli la voce che corrisponde alla lingua della tua UI e ripiega su name_default.

Aspettati che ingredients sia più lungo del numero di lingue: Open Food Facts memorizza il testo degli ingredienti per variante di confezione, quindi la stessa lang può comparire più di una volta in un record, spesso con testo identico, come qui. Deduplica per lang e tieni la prima occorrenza. Il testo è inserito dai contributori e restituito così com'è; la voce ar qui contiene frammenti d'etichetta che non sono ingredienti, quindi convalida prima di trasformarla in strutture.

Categoria, tag, allergeni e lang

category è un'unica stringa unita da virgole, dal generale allo specifico: Beverages and beverages preparations,Beverages,Carbonated drinks,Sodas,Colas,pt:bebidas cafeína. Dividi sulla virgola; l'ultimo livello è il più specifico. categories_tags contiene gli stessi livelli come tag leggibili da macchina (en:beverages, en:carbonated-drinks, en:colas) ed è il valore stabile su cui filtrare o raggruppare, perché la stringa di visualizzazione cambia quando i contributori modificano il prodotto.

allergens e traces usano gli stessi tag in stile en:milk, così come countries (en:albania, en:austria, en:belgium) e labels. null significa che la fonte non ha dichiarato nulla, non che il prodotto sia privo di allergeni; questo record ha allergens: null e traces: null, quindi un avviso allergeni dovrebbe dire sconosciuto, non nessuno.

Con ?lang=bg l'API aggiunge category_localized come singola stringa tradotta, category_segments_localized con una voce per livello della gerarchia, e allergens_localized parallelo a allergens. Un livello o un tag senza voce nel dizionario è null dentro l'array, quindi mantieni l'indice allineato con categories_tags o allergens e ripiega sul tag inglese per gli slot null.

Punteggi, dimensione della porzione e nutrienti di riepilogo

nutriscore è una lettera minuscola (e qui), nova_group un numero (4) ed ecoscore_grade una stringa che può essere una lettera o un valore sentinella come not-applicable, che è ciò che restituisce questa bevanda. Tratta tutti e tre come nullable e non associare not-applicable a una fascia di colore.

serving_size_raw e quantity sono testo libero copiato dall'etichetta. serving_size_raw dice 1 can (330 ml) e va bene per la visualizzazione; quantity dice 0kg in questo record, un errore di un contributore, quindi non calcolare mai il peso della confezione da esso senza un controllo di coerenza.

nutrition_summary fornisce sei valori per 100 g: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g e fiber_g. Ognuno può essere null da solo e l'oggetto può essere null quando la fonte non ha una tabella nutrizionale. Copre una riga di elenco o un confronto rapido; i 40+ nutrienti completi sono nella Nutrition API su /v1/foods/{id}/nutrients con lo stesso id.

Id stabili, cache e flusso abituale

L'id è deterministico, derivato dalla fonte e dall'id di prodotto della fonte stessa, quindi lo stesso prodotto ottiene lo stesso UUID a ogni reimportazione. Salva gli id nelle tue tabelle e recuperali di nuovo mesi dopo senza alcun passaggio di rimappatura. barcode può essere null nello schema, quindi preferisci l'id al codice a barre come chiave di join.

Un 200 porta Cache-Control: public, max-age=300 e un 404 porta max-age=60, quindi una CDN o una cache HTTP davanti al tuo servizio li rispetta senza configurazione. Se metti in cache nel tuo database, usa come chiave id più lang, perché le chiavi localizzate cambiano da lingua a lingua.

Il flusso abituale: ottieni un id dalla Food Search API o dalla Barcode Lookup API, salvalo e chiama questo endpoint quando una vista di dettaglio ha bisogno del record completo. Per aggiornare molti id salvati in una volta, la Bulk Food Lookup API accetta un elenco in una richiesta dallo Starter in su. Le immagini sono foto dei contributori di Open Food Facts ospitate su images.openfoodfacts.org e i record di altre fonti potrebbero non averne, quindi mostra un segnaposto ogni volta che image_url è null.