Il dataset sulla caffeina

Che cosa contiene il file e cosa significa ciascun campo?

Il file è un export pubblicato in JSON e CSV del dataset aperto di 87 bevande ospitato in questa pagina e contiene esattamente i campi id, name, brand, category, serving_ml, caffeine_mg, caffeine_per_100ml, scales_with_volume e is_decaf. Il dataset è la tabella di 87 voci delle bevande pubblicata in questa pagina.

Il formato del file contiene un record per ogni bevanda; ogni record nel file corrisponde direttamente a una riga del CSV e a un oggetto nel JSON, e il dataset conta 87 record distribuiti in 8 categorie: espresso 12, brewed 8, coffeeShop 20, energy 15, tea 11, soda 11, preworkout 5 e other 5 (i conteggi per categoria fanno parte del dataset). Ciascuno di questi numeri è registrato nel dataset e reso disponibile per filtraggio programmatico tramite l'export /dataset/.

id è un identificatore breve macchina usato per cercare un record nel JSON e nel CSV. Il campo id è unico per ciascuno dei 87 record ed è la chiave primaria per join programmatici contro il dataset.

name è il nome leggibile dall'utente della bevanda così come appare nelle pagine pubbliche delle bevande come Espresso (single) dove il nome mostra "Espresso (single)" e la pagina riporta 63 mg; la cifra 63 mg è registrata in caffeine_mg per quell'elemento nel dataset.

brand è il proprietario commerciale o la fonte quando applicabile, oppure una stringa vuota per elementi generici; per esempio la riga del dataset per Starbucks Pike Place Brewed (Grande) elenca Starbucks come brand nel campo brand e 310 mg nel campo caffeine_mg.

category è il raggruppamento categoriale che classifica ogni record in uno degli otto gruppi (espresso, brewed, coffeeShop, energy, tea, soda, preworkout, other); category è un'etichetta categoriale usata per aggregare i conteggi (il dataset contiene 12 elementi espresso, 8 elementi brewed, e così via) e tali conteggi sono elencati nell'intestazione del dataset.

serving_ml è il volume della porzione in millilitri. Per esempio, Espresso (single) ha serving_ml 30 ml e Starbucks Pike Place Brewed (Grande) ha serving_ml 473 ml; entrambi i numeri sono registrati nel dataset.

caffeine_mg è la quantità assoluta di caffeina in milligrammi per porzione. Caffeine_mg è il valore numerico di caffeina assegnato a ciascuna porzione; per esempio il dataset registra caffeine_mg 63 mg per Espresso (single) e 310 mg per Starbucks Pike Place Brewed (Grande).

caffeine_per_100ml è la concentrazione normalizzata di caffeina in mg per 100 ml quando quel valore è appropriato e disponibile; caffeine_per_100ml è la metrica di concentrazione usata per confrontare l'intensità tra diverse dimensioni di porzione e il dataset memorizza questo valore per voci come Cold brew (83.3 mg/100 ml) e Drip coffee (40 mg/100 ml).

scales_with_volume è un flag booleano che indica se il valore di caffeina si prevede vari approssimativamente in modo lineare con il volume (true/false). Scales_with_volume è true per i caffè semplici filtrati dove la concentrazione è approssimativamente costante, e false per elementi basati sull'unità come una singola dose di espresso dove la caffeina dipende dalla singola unità piuttosto che essere proporzionale agli ml.

is_decaf è un flag booleano che marca le bevande preparate decaffeinate; is_decaf è true per gli elementi decaffeinati e il dataset mostra, per esempio, che Decaf coffee ha caffeine_mg 3 mg e is_decaf true.

Come viene inserito un valore nel dataset e cosa squalifica un candidato?

I valori vengono aggiunti solo dopo che è stata verificata una fonte documentata e definita una chiara dimensione della porzione; le voci provengono da etichette dei fornitori, tabelle nutrizionali pubblicate nei menu, saggi di laboratorio come USDA FoodData Central, o misurazioni peer-reviewed quando esistono. USDA FoodData Central è una delle fonti di riferimento usate per valori dichiarati o misurati e quella fonte è esplicitamente citata nelle pagine degli articoli quando viene utilizzata (USDA FoodData Central).

L'inclusione richiede un caffeine_mg numerico verificabile e un serving_ml stabile o una chiara ragione per cui l'elemento è basato sull'unità (per esempio colpi di espresso o pillole di caffeina). I record senza una porzione verificabile o senza un valore numerico di caffeina vengono squalificati e non aggiunti all'export pubblico.

Accettiamo valori dichiarati dal produttore (etichette nutrizionali o menu pubblicati) quando quelle etichette corrispondono alla definizione della porzione; un'etichetta dichiarata che indica 200 mg per una bottiglia da 300 ml verrà registrata solo se la dimensione della bottiglia è esplicita e corrisponde al serving_ml nella riga del dataset, e ogni inclusione di questo tipo indica la fonte nella pagina della bevanda.

Accettiamo misurazioni di laboratorio indipendenti come le voci indicizzate dall'USDA quando il saggio riporta unità coerenti con il nostro serving_ml; quando USDA o un metodo peer-reviewed riporta una concentrazione in mg/100 ml convertiamo tale valore in caffeine_mg per il serving_ml registrato e citiamo il saggio originale nella pagina della bevanda e nei metadati del dataset (USDA FoodData Central).

Squalifichiamo valori candidati se la dimensione della porzione è ambigua (per esempio una fascia di menu senza una porzione standard), se la fonte è aneddotica senza un metodo misurabile, o se il valore riportato contraddice più fonti affidabili senza riconciliazione. Gli elementi con ampia variabilità e senza una porzione rappresentativa verranno esclusi finché non sarà stabilito un valore singolo affidabile.

Non inventiamo serving_ml o caffeine_mg; ogni numero nel file esportato è supportato dalle righe del dataset autenticate e, quando la fonte è dichiarata dal produttore, la pagina della bevanda rimanda al menu o all'etichetta sottostante quando disponibile.

Le correzioni e le contestazioni vengono gestite tramite il processo di correzione descritto nella pagina about e tramite il modulo di contatto; vedi /about/ per il metodo e /contacts/ per come inviare correzioni dei dati.

Perché le cifre pubblicate sulla caffeina differiscono tra le fonti?

Le cifre pubblicate sulla caffeina differiscono perché lo stesso nome di bevanda può rappresentare diverse dimensioni di porzione, diverse intensità di infusione, diverse formulazioni regionali o diverse convenzioni di misurazione; questi quattro fattori concreti spiegano la maggior parte delle differenze osservate nel dataset. Queste fonti di disaccordo sono documentate nelle singole pagine delle bevande dove il dataset elenca il numero usato e la provenienza di quel numero.

Le convenzioni sulle dimensioni delle porzioni cambiano i totali riportati: per esempio il dataset registra Starbucks Pike Place Brewed (Grande) come 310 mg in una porzione da 473 ml mentre un menu locale può riportare una dimensione diversa; la cifra 310 mg nel dataset proviene dalla dichiarazione nutrizionale pubblicata da Starbucks per una porzione Grande da 473 ml ed è citata nella pagina della bevanda.

Le differenze nella forza dell'infusione sono una causa frequente: il drip coffee nel nostro dataset è 96 mg per 240 ml mentre il pour over è elencato come 145 mg per 240 ml; entrambi i valori sono nel dataset e riflettono diverse intensità di estrazione e rapporti macinatura/infusione. Il dataset registra drip coffee 96 mg (240 ml) e pour over 145 mg (240 ml) e quei valori specifici sono disponibili nelle rispettive pagine (Drip coffee, Pour over).

Le formulazioni regionali o le differenze di ricetta cambiano la caffeina dichiarata: una voce di Coca-Cola in bottiglia mostra 32–34 mg per lattina a seconda dell'imballaggio da 330 ml o 355 ml, e il dataset contiene sia Coca-Cola (330 ml) 32 mg sia Coca-Cola (355 ml) 34 mg per riflettere le differenze di confezionamento ed etichettatura.

L'arrotondamento delle etichette e le differenze dichiarato vs misurato creano piccole discrepanze: i produttori a volte dichiarano numeri arrotondati nelle tabelle nutrizionali e i laboratori riportano valori misurati con maggiore precisione; il dataset preserva il numero dichiarato sull'etichetta quando quello è la fonte pubblicata e indica le concentrazioni misurate quando disponibili.

Le fonti degli ingredienti e gli stimolanti aggiunti possono modificare la caffeina oltre caffè/tè: le bevande energetiche e gli integratori pre-workout a volte usano caffeina anidra, guaranà o altri ingredienti che cambiano il totale in mg e la concentrazione; il nostro dataset registra il caffeine_mg finale come dichiarato dal brand o misurato in fonti pubbliche come le pagine del prodotto elencate nelle pagine di dettaglio degli articoli.

Quali sono i limiti noti di questo dataset?

Questo dataset fornisce un singolo caffeine_mg rappresentativo per bevanda e non cattura la variabilità intra-lotto o per barista; l'approccio a valore singolo è una scelta progettuale e significa che l'export non può rappresentare l'intera distribuzione delle concentrazioni per una bevanda. Per esempio il dataset elenca Cold brew a 200 mg per 240 ml e Nitro cold brew a 215 mg per 240 ml, ma le singole preparazioni varieranno intorno a quei numeri.

La farmacocinetica di popolazione e la sensibilità individuale sono al di fuori del dataset; il dataset è una tavola di contenuti delle quantità di caffeina nelle bevande e non fornisce raccomandazioni di dosaggio personali o consigli medici. Le linee guida sull'assunzione giornaliera sicura sono disponibili da enti regolatori e il dataset fa riferimento a tali linee guida: la US Food and Drug Administration indica 400 mg al giorno come linea guida per adulti sani (FDA).

Gli elementi decaffeinati non sono zero: il dataset registra Decaf coffee come 3 mg in 240 ml, il che dimostra che le preparazioni decaffeinate spesso mantengono piccole quantità residue di caffeina e non devono essere considerate prive di caffeina.

Alcuni record sono basati su unità e hanno serving_ml 0 per comodità (per esempio pillole e gomme); il dataset elenca Caffeine pill (200 mg) come 200 mg e serving_ml 0, il che riflette che il volume non è applicabile per quegli elementi ed è una limitazione per i confronti per volume.

Non esaustivo né globalmente completo: il dataset contiene 87 record selezionati per rappresentare bevande e marchi comuni ed è intenzionalmente limitato; l'export non è un tentativo di includere ogni prodotto nel mondo, e gli utenti dovrebbero trattare la raccolta come un campione curato piuttosto che come un catalogo esaustivo.

Rimangono possibili differenze tra laboratorio e dichiarato: quando più fonti affidabili discordano selezioniamo la fonte più specifica e documentiamo la scelta nella pagina della bevanda; per qualsiasi voce puoi trovare il link di provenienza nella pagina individuale e contattarci se hai una misurazione contraddittoria su /contacts/.

Come devo citare o riutilizzare questo dataset?

Il dataset è concesso in licenza sotto CC BY 4.0 e richiede attribuzione a TrackCaffeine; CC BY 4.0 è la licenza applicata al dataset ed è linkata qui per i termini legali (CC BY 4.0). Il formato di citazione raccomandato è TrackCaffeine Dataset (2026). TrackCaffeine è ripetuto come destinatario dell'attribuzione e la pagina di export del dataset è l'URL canonico da includere in tale attribuzione.

Usa questo breve esempio di citazione quando riutilizzi i dati: "TrackCaffeine. Open caffeine dataset. CC BY 4.0. https://trackcaffeine.com/dataset/" e includi un link a /dataset/ per la provenienza e la versione del dataset utilizzata. Se modifichi valori o aggregi più elementi, indica la trasformazione e mantieni l'attribuzione originale a TrackCaffeine come richiesto da CC BY 4.0 (CC BY 4.0).

Il riutilizzo commerciale è consentito sotto CC BY 4.0 purché venga fornita l'attribuzione; la pagina della licenza linkata sopra spiega gli obblighi legali e la pagina del dataset stessa documenta la versione del dataset utilizzata in qualsiasi opera derivata.

Quali esempi funzionanti mostrano come calcolare con il file, inclusa la decadenza e l'equivalenza in tazze di caffè?

Puoi calcolare la caffeina residua nel tempo usando un modello di eliminazione del primo ordine con emivita media della popolazione 5.7 hours; l'eliminazione del primo ordine è il modello farmacocinetico dove la velocità di eliminazione è proporzionale alla concentrazione corrente. Il modello usato qui è remaining = dose × 0.5^(hours ÷ 5.7) e l'emivita 5.7 hours è la media di popolazione usata nei nostri calcolatori.

Esempio 1: calcolare la caffeina residua dopo 6 hours per Starbucks Pike Place Brewed (Grande). Starbucks Pike Place Brewed (Grande) è 310 mg in 473 ml secondo il dataset, quindi remaining = 310 mg × 0.5^(6 ÷ 5.7) che si valuta come remaining = 310 mg × 0.5^(1.052631579) = 310 mg × 0.482 ≈ 149 mg; il valore del dataset 310 mg è mostrato nella pagina della bevanda e l'aritmetica è eseguita con il modello di primo ordine riportato sopra.

Esempio 2: calcolare la caffeina residua dopo 3 hours da una bevanda energetica da 300 mg come Bang (Bang è registrata come 300 mg per 473 ml nel dataset). Usando remaining = 300 mg × 0.5^(3 ÷ 5.7) = 300 mg × 0.5^(0.526315789) = 300 mg × 0.697 ≈ 209 mg rimanenti; il dataset elenca Bang come 300 mg e l'aritmetica usa il numero del dataset con il modello di emivita sopra.

Esempio 3: equivalenza in tazze di caffè: quante latte equivalgono a un drip coffee? Drip coffee è 96 mg per 240 ml e Latte è 68 mg per 240 ml nel dataset. Usa ratio = 96 mg ÷ 68 mg = 1.411764706, quindi un drip coffee equivale a circa 1.41 latte; entrambi i numeri di origine sono registrati nelle pagine delle bevande per Drip coffee (96 mg) e Latte (68 mg).

Esempio 4: equivalenza in colpi di espresso: quanti espresso singoli (63 mg) equivalgono a un Starbucks Grande brewed da 310 mg? Usa ratio = 310 mg ÷ 63 mg = 4.920634921, quindi circa 4.92 espresso singoli equivalgono alla porzione Grande brewed; gli input numerici 310 mg e 63 mg provengono dalle rispettive pagine delle bevande Starbucks Pike Place Brewed (Grande) e Espresso (single).

Esempio 5: usare il dataset con i calcolatori. Se vuoi decadimento interattivo o pianificazione per l'ora di andare a letto puoi incollare un valore caffeine_mg dal JSON nei calcolatori su /tools/caffeine-calculator/, confrontare due bevande su /tools/caffeine-comparison/, o stimare gli effetti dell'ultima tazza prima di dormire usando /tools/last-cup-before-bed/. Ogni calcolatore usa lo stesso modello di eliminazione del primo ordine e il JSON esportato è formattato per copia/incolla in quegli strumenti.

Citazione concreta sull'impatto sul sonno: uno studio controllato riporta che 400 mg di caffeina assunti sei ore prima dell'ora di coricarsi hanno ridotto il tempo totale di sonno di oltre un'ora; quello studio è citato qui ed è rilevante quando usi il dataset per pianificare l'assunzione (Drake et al., 2013). Usa i valori del dataset per calcolare quanto una porzione si avvicina alla soglia di 400 mg e poi usa lo studio per interpretare i potenziali effetti sul sonno.

Se vuoi replicare uno di questi calcoli programmaticamente, carica il CSV o il JSON da /dataset/, seleziona caffeine_mg per l'ID che vuoi, e valuta remaining = dose × 0.5^(hours ÷ 5.7) con la dose numerica dal dataset; i calcolatori linkati sotto /tools/ usano lo stesso approccio e sono pensati per l'esplorazione interattiva.

Per riferimento rapido alle pagine delle bevande comuni usate negli esempi, vedi Espresso (single), Drip coffee, Cold brew, Starbucks Pike Place Brewed (Grande), Bang, Latte, e i calcolatori su /tools/caffeine-calculator/, /tools/caffeine-comparison/, /tools/last-cup-before-bed/.

Correzioni, richieste di nuove voci o domande sulla provenienza dovrebbero essere inviate tramite il modulo di contatto su /contacts/, e il changelog del dataset e le note sul metodo sono disponibili su /about/ dove descriviamo la selezione delle fonti e la frequenza degli aggiornamenti.

Questa documentazione è informativa e destinata al riuso dei dati; non è un consiglio medico. Per indicazioni sulla salute riguardo i limiti sicuri di caffeina consulta fonti regolatorie o cliniche come la US Food and Drug Administration che indica 400 mg al giorno per adulti sani (FDA) o l'European Food Safety Authority per pareri regionali (EFSA, 2015).

Licenza e attribuzione: questo dataset è pubblicato sotto CC BY 4.0; includi l'attribuzione a TrackCaffeine e un link a CC BY 4.0 quando riutilizzi i dati. Se riutilizzi grandi porzioni del dataset in un prodotto pubblico, includi un link a /dataset/ e una breve nota di provenienza che nomini TrackCaffeine come fonte.