Primi passi con FoodBase

Crea il tuo account

Vai alla pagina di registrazione e crea un account gratuito. Nessuna carta di credito richiesta — il piano gratuito ti dà 100 richieste API al giorno, più che sufficienti per testare e fare prototipi.

Genera una chiave API

Una volta effettuato l’accesso, vai su Dashboard > API Keys e clicca su Create key. Dagli un nome descrittivo come «My App» o «Development». La chiave completa viene mostrata una sola volta, quindi copiala e conservala in un posto sicuro (come un file .env o un gestore di password).

La tua chiave avrà un aspetto simile a questo: food_KV23NskbwXkKzi1yaPdPF1

Fai la tua prima richiesta

Cerca un prodotto alimentare per nome:

curl "https://foodbase.dev/v1/foods/search?q=banana&limit=3" \
  -H "X-API-Key: food_your_key_here"

La risposta include i prodotti corrispondenti con nomi, marchi, categorie e dati nutrizionali di base:

{
  "data": [
    {
      "id": "abc-123",
      "name_default": "Banana",
      "brand": null,
      "category": "Fresh fruits",
      "nutriscore": "a"
    }
  ],
  "total": 26080,
  "limit": 3,
  "offset": 0
}

Ricerca per codice a barre

Se stai creando un’app con scanner di codici a barre, usa l’endpoint dei codici a barre con un codice EAN-13 o UPC:

curl "https://foodbase.dev/v1/foods/barcode/5449000000996" \
  -H "X-API-Key: food_your_key_here"

Restituisce i dettagli completi del prodotto, incluso un riepilogo nutrizionale con calorie, proteine, carboidrati, grassi, zuccheri e fibre — tutto per 100 g.

Ottieni i nutrienti dettagliati

Per la ripartizione completa dei nutrienti (oltre 40 valori organizzati per categoria), usa l’endpoint dei nutrienti. È disponibile su ogni piano — il piano Free include 25 ripartizioni al giorno (tieni d’occhio l’header X-RateLimit-Nutrients-Remaining), i piani a pagamento non hanno limiti:

curl "https://foodbase.dev/v1/foods/{id}/nutrients" \
  -H "X-API-Key: food_your_key_here"

La risposta raggruppa i nutrienti per categoria:

• Macro — energia (kcal/kJ), proteine, carboidrati, grassi, fibre, zuccheri, alcol, amido
• Grassi — saturi, trans, mono/polinsaturi, omega-3/6, colesterolo
• Minerali — sodio, calcio, ferro, potassio, magnesio, zinco e altri
• Vitamine — A, C, D, E, complesso B (B1, B2, B6, B9, B12), niacina

Ricerche in blocco

Devi recuperare più prodotti in una volta? Usa l’endpoint bulk con fino a 100 ID:

curl -X POST "https://foodbase.dev/v1/foods/bulk" \
  -H "X-API-Key: food_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["id-1", "id-2", "id-3"]}'

I risultati vengono restituiti nello stesso ordine degli ID in ingresso — non serve riordinarli dal tuo lato.

Prova gli endpoint IA

Ogni piano — compreso Free — include una dotazione mensile di crediti IA (20 su Free). Alimentano gli endpoint di visione e di analisi: identificare un prodotto da una foto, leggere un’etichetta nutrizionale, analizzare un pasto o generare un riassunto IA in linguaggio semplice di qualsiasi prodotto. Ogni chiamata ha un prezzo fisso in crediti indicato nella documentazione, e ogni risposta IA contiene gli header X-Credits-Remaining.

Il modo più veloce per vederli all’opera è il playground foto — carica una foto direttamente nel browser con la tua chiave. Oppure chiamane uno direttamente:

curl -X POST "https://foodbase.dev/v1/analyze/product" \
  -H "X-API-Key: food_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"barcode": "3017620422003"}'

Limiti di velocità che non ti ostacolano

I limiti al secondo sono token bucket: la velocità del tuo piano è il ritmo sostenuto (Free = 1 richiesta/s) e in più hai un burst pari a 5 volte quel valore — quindi una pagina che lancia alcune richieste in parallelo funziona senza problemi. Ogni risposta include degli header così la tua app può monitorare l’utilizzo:

X-RateLimit-Second-Limit: 1
X-RateLimit-Burst-Capacity: 5
X-RateLimit-Second-Remaining: 4
X-RateLimit-Daily-Limit: 100
X-RateLimit-Daily-Remaining: 97
X-RateLimit-Daily-Reset: 2026-04-14T23:59:59Z

Se ricevi un 429, contiene sempre un header Retry-After con i secondi da attendere prima che maturi il prossimo token — rispettalo (la maggior parte dei client HTTP può farlo in automatico) e tornerai a ricevere 200 il più in fretta possibile consentito dal limitatore. Per recuperare molti prodotti in una volta, POST /foods/bulk è una richiesta invece di N.

Prossimi passi

• Sfoglia la documentazione dell’API per tutti gli endpoint disponibili e provali in modo interattivo
• Esplora tu stesso il database nell’esploratore di prodotti — ogni pagina prodotto mostra esattamente ciò che restituisce l’API
• Controlla le tue statistiche di utilizzo per monitorare le richieste giornaliere
• Passa a un piano superiore quando ti serve più capacità
• Leggi la nostra guida ai dati nutrizionali per capire la copertura dei dati