API nutrizionali

Una richiesta, cinque gruppi, per 100 g

GET /v1/foods/{id}/nutrients prende l'UUID dell'alimento nel percorso e nient'altro: nessun parametro di query, nessun corpo, nessuna lang. L'id è lo stesso che restituisce ogni altro endpoint, quindi un risultato della Food Search API o della Barcode Lookup API diventa un dettaglio completo con una chiamata in più. Gli id sono deterministici tra le reimportazioni, quindi puoi salvarli e continuare a chiamare questo URL.

La risposta è un oggetto piatto con food_id più cinque gruppi fissi: macros, fats, minerals, vitamins e other. Ogni chiave è sempre presente e ogni valore è un numero oppure null. Contando le chiavi dello schema attuale si arriva a 41 campi nutrizionali, da cui il “40+”. Le unità sono nel nome della chiave (energy_kcal, sodium_mg, selenium_mcg, vitamin_a_iu), quindi non devi portarti dietro una tabella di unità separata.

Tutti i valori sono per 100 g di prodotto così come venduto. Per mostrare una porzione, moltiplica per i grammi divisi per 100. Il serving_size_raw del record alimentare è testo d'etichetta (per il record Coca-Cola dell'esempio è “1 can (330 ml)”), quindi la conversione da quel testo ai grammi spetta a te.

• macros (10 chiavi) copre energia in kcal e kJ, proteine, carboidrati, grassi, zuccheri, fibre, alcol, amido e polioli; fats (7) aggiunge saturi, trans, mono e polinsaturi, omega3, omega6 e cholesterol_mg
• minerals (12) va da sodium_mg e salt_g a selenium_mcg e iodine_mcg; vitamins (11) riporta A e D in IU, B9 e B12 in mcg, le altre in mg; other contiene added_sugars_g

Leggere correttamente null e zeri

La risposta di esempio per l'alimento 62ea12b8-b260-c288-5c38-3a4906f5d6dd mostra il tipico schema di Open Food Facts: energy_kcal 42, energy_kj 180.2, carbs_g 10.6, sugars_g 10.6, added_sugars_g 5.3, zeri espliciti per proteins_g, fat_g, saturated_fat_g, sodium_mg e salt_g, e null per tutto il resto, da fiber_g all'intero gruppo vitamins.

Tratta i due stati in modo diverso. Uno 0 è un valore riportato dalla fonte; un null significa che il nutriente non è in etichetta o non è nella fonte. Non convertire mai null in 0 prima di sommare l'assunzione di una giornata, altrimenti un pasto composto da prodotti etichettati solo in parte sottostimerà in silenzio vitamine e minerali. Mostra un trattino o “non riportato”.

La copertura segue la provenienza. Le righe con source usda_foundation o usda_sr_legacy sono analisi di laboratorio USDA e popolano i gruppi vitamine e minerali, quindi la maggior parte delle chiavi ha un numero. Le righe con source usda (USDA Branded Foods) e quelle di Open Food Facts sono trascritte dalla confezione, quindi sono affidabili per i nutrienti obbligatori in etichetta e spesso null oltre quelli. Il campo source del record alimentare ti dice in quale caso sei prima di mostrare la tabella.

• Mostra null come sconosciuto, non come zero; aggrega solo le chiavi non null in ogni elemento del pasto.
• sodium_mg e salt_g esistono entrambi perché le etichette cambiano da regione a regione; usa quello che si aspetta il tuo pubblico e ripiega sull'altro.

Quando ti serve davvero questa chiamata

Ogni record alimentare della Food Database API e ogni corrispondenza per codice a barre include già nutrition_summary con sei valori principali: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g e fiber_g. Le righe di ricerca sono più leggere e non lo hanno. Per il risultato di una scansione, una scheda di dettaglio o un rapido registro delle calorie, quell'oggetto di solito basta e non consuma alcun dettaglio nutrizionale.

Riserva /nutrients alla schermata di dettaglio o al momento in cui l'utente chiede di sodio, grassi saturi, colesterolo o di una vitamina specifica. Cerca o scansiona, mostra il riepilogo, recupera il dettaglio al tocco. Nel piano Free è anche ciò che ti tiene entro il limite di 25 al giorno mentre sviluppi.

Gli header di risposta catturati non hanno Cache-Control, quindi la cache spetta a te. Gli id sono stabili e i valori cambiano solo quando un prodotto viene reimportato, quindi una cache con chiave food_id e conservata per ore o giorni è sicura.

Il limite del piano Free, header per header

Nel piano Free ogni dettaglio riuscito scala un contatore giornaliero separato di 25, riportato in ogni risposta come X-RateLimit-Nutrients-Limit, X-RateLimit-Nutrients-Remaining e X-RateLimit-Nutrients-Reset. Leggi Remaining prima di una raffica di richieste di dettaglio e potrai ripiegare su nutrition_summary invece di sbattere contro il muro a metà sessione.

A zero l'endpoint restituisce 429 con error “Nutrients daily allowance exceeded”, un upgrade_url nel corpo e Retry-After con i secondi fino alla mezzanotte UTC. Una chiamata rifiutata non consuma né un dettaglio né una richiesta giornaliera, e non sposta il reset. I piani a pagamento non hanno questo contatore; le loro chiamate ai nutrienti sono limitate solo dalla quota giornaliera di richieste del piano (condivisa tra tutte le chiavi dell'account) e dal limite al secondo per chiave.

Se sei su Starter o superiore e stai lavorando su un grande catalogo, recupera prima i record di base con la Bulk Food Lookup API e chiama /nutrients solo per gli id il cui riepilogo non basta.