API delle categorie alimentari
Sfoglia ogni categoria alimentare con il suo numero di prodotti — la base per filtri, faccette e navigazione. JSON paginato sull'intero catalogo, servito da una vista precalcolata per restare veloce.
curl -H "X-API-Key: food_•••" \
"https://foodbase.dev/v1/categories"
{
"data": [
{ "category": "Popcorn, Peanuts, Seeds & Related Snacks", "product_count": 95496 },
{ "category": "Candy", "product_count": 92693 },
{ "category": "Cheese", "product_count": 85564 }
],
"total": 306779
}Preferisci cliccare? Prova l'esploratore di prodotti o l'area di prova foto.
Cosa ottieni
category
Il nome della categoria.
product_count
Quanti prodotti vi rientrano.
total
Numero di categorie distinte.
Pronto per i filtri
Combinalo con la ricerca per limitare i risultati a una categoria.
Incluso nel piano gratuito — 100 richieste/giorno, nessuna carta di credito richiesta. Vedi i piani →
Esempi di codice
La stessa richiesta in curl, JavaScript e Python. Sostituisci YOUR_API_KEY con una chiave della tua dashboard.
curl "https://foodbase.dev/v1/categories?q=chocolate&limit=10" \
-H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://foodbase.dev/v1/categories?q=chocolate&limit=10", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
import requests
res = requests.get(
"https://foodbase.dev/v1/categories?q=chocolate&limit=10",
headers={"X-API-Key": "YOUR_API_KEY"},
timeout=30,
)
res.raise_for_status()
data = res.json()
Come funziona
Cosa restituisce una singola richiesta
GET /v1/categories legge una tabella precalcolata con ogni stringa di categoria distinta del catalogo e il numero di prodotti che la portano; i prodotti senza categoria sono esclusi. Le righe sono ordinate per product_count decrescente senza un secondo criterio, quindi non fare affidamento sull'ordine delle righe con lo stesso conteggio.
q è un filtro per sottostringa senza distinzione tra maiuscole e minuscole, non un prefisso: q=chocolate corrisponde a “Chocolate”, “en:chocolates” e “Beverages, Dairies, Dairy drinks, Flavoured milks, Chocolate milks” allo stesso modo, restringendo la risposta catturata a un total di 11303 stringhe distinte. Gli spazi vengono rimossi, % e _ sono letterali e q è limitata a 200 caratteri.
limit va da 1 a 100 (predefinito 20) e offset da 0 a 10000, quindi con limit=100 puoi raggiungere al massimo le prime 10.100 righe; restringi con q invece di paginare più a fondo. Le risposte portano Cache-Control: public, max-age=600, il server le mette in cache per un'ora e la tabella viene ricostruita solo a una reimportazione massiva, quindi recuperala una volta all'avvio o in una fase di build e conserva il risultato.
Due forme di stringa di categoria
I prodotti di Open Food Facts portano una gerarchia unita da virgole, dal generale allo specifico: “Snacks, Sweet snacks, Cocoa and its products, Chocolates, Dark chocolates”. I segmenti possono essere tag grezzi della tassonomia con un prefisso di lingua di due lettere (“en:chocolate-candies”), possono essere nella lingua dell'etichetta (“Botanas, Snacks dulces, Cacao y sus productos, Chocolates, Chocolates negros”) e spesso finiscono con un termine generico come en:groceries che non è il livello più specifico.
I prodotti USDA portano un'unica categoria di vendita piatta il cui nome può contenere a sua volta virgole (“Chips, Pretzels & Snacks”); non dividerla mai. Le righe qui non riportano la fonte, quindi quando ti serve, recupera un prodotto della categoria con la Food Database API e leggi source accanto a category e categories_tags.
Una stessa gerarchia può comparire come più righe: la risposta catturata elenca separatamente “Snacks, Sweet snacks, Cocoa and its products, Chocolates, Dark chocolates” (497 prodotti) e lo stesso percorso senza spazi dopo le virgole (339). Unisci sui segmenti ripuliti, non sulla stringa grezza.
Costruire un albero di navigazione o un'interfaccia di filtri
Applica la pulizia che usa il sito: dividi sulle virgole, rimuovi gli spazi, togli un eventuale tag iniziale xx:, sostituisci i trattini con spazi, metti in maiuscolo la prima lettera ed elimina i segmenti ripetuti senza distinguere maiuscole e minuscole. Il primo segmento ripulito è la radice; l'ultimo che non è un termine generico (groceries, food, foods, products, unknown, none) è la foglia. Il conteggio di un nodo è la somma di product_count su ogni stringa grezza che vi corrisponde.
- Nodi radice: raggruppa per primo segmento ripulito (“Snacks”, “Beverages”, “Botanas”).
- Chip delle foglie: l'ultimo segmento che non sia un termine generico (“Dark chocolates”, “Chocolate milks”).
- Nomi USDA piatti: l'intera stringa è sia radice sia foglia.
- Lingua: le gerarchie in lingue diverse restano nodi separati; per le traduzioni per prodotto passa lang= alla Food Search API e leggi category_localized e category_segments_localized.
- L'albero di navigazione del sito su /categories/ applica le stesse regole di pulizia a questi dati (e tiene solo le foglie più grandi); usalo per verificare il tuo output.
Da una categoria ai suoi prodotti
La ricerca non ha un parametro di categoria. La Food Search API confronta prima nomi di prodotto e marche e, solo quando non trova nulla, confronta le parole della tua query con le stringhe di categoria. Invia come q un segmento completo e ripulito che non sia a sua volta un nome di prodotto, come “Seeds & Related Snacks”, e otterrai i prodotti di quella categoria ordinati per popolarità.
Il ripiego è basato sulle parole, quindi “Seeds & Related Snacks” corrisponde a ogni stringa di categoria che contiene quelle parole in qualsiasi lingua, e un segmento che è anche una parola comune di prodotto (“Chocolate” o “Dark chocolates”) non lo raggiunge mai, perché i nomi dei prodotti corrispondono per primi. Per un elenco rigoroso, filtra ogni risultato sul suo campo category, che è la stringa grezza restituita da questo endpoint.
Cosa puoi costruire
Filtri e faccette
Mostra la navigazione per categoria con il numero di prodotti aggiornato in tempo reale.
Panoramiche del catalogo
Mostra agli utenti la forma del dataset prima che cerchino.
Dashboard di analisi
Visualizza in un grafico come si distribuiscono i prodotti tra le categorie.
Limiti per piano
| Free | 100 richieste/giorno condivise tra gli endpoint, 1/s (burst 5); abbastanza per aggiornare un albero in cache alcune volte al giorno. |
|---|---|
| Starter | 5.000 richieste/giorno, 5/s (burst 25). |
| Pro | 25.000 richieste/giorno, 20/s (burst 100). |
| Enterprise | 100.000 richieste/giorno, 50/s (burst 250). |
Ogni risposta include gli header X-RateLimit-* con il budget residuo; ogni 429 include Retry-After . Confronta i piani →
Errori e come gestirli
401 — X-API-Key è mancante, non valida o revocata.
Invia una chiave dalla dashboard; il campo error del corpo dice quale caso è.
422 — limit fuori dall'intervallo 1–100, offset fuori dall'intervallo 0–10000, oppure q oltre i 200 caratteri.
Limita i valori lato client; qui la convalida restituisce 422, non 400.
429 — Il limite al secondo della chiave o la quota giornaliera dell'account è esaurita.
Attendi Retry-After e nel frattempo servi la tua copia in cache.
Confronto con altre API
Questo è un elenco di stringhe di categoria così come sono memorizzate, con i conteggi, non una tassonomia curata. I contributori di Open Food Facts e l'importazione USDA forniscono ciascuno la propria forma, spaziatura, lingua e tag, e l'endpoint non li unisce; le regole di pulizia qui sopra le applichi tu. In cambio i conteggi corrispondono esattamente al catalogo e ogni stringa può essere passata direttamente alla ricerca o confrontata con il campo category di un prodotto. Costruisci un unico albero normalizzato a partire da questo elenco e mettilo in cache, perché i dati cambiano solo alla reimportazione.
Domande frequenti
q è una corrispondenza per prefisso o per sottostringa? +
Sottostringa, senza distinzione tra maiuscole e minuscole, in qualsiasi punto della stringa; q=chocolate restituisce sia “Beverages, Dairies, Dairy drinks, Flavoured milks, Chocolate milks” sia “Chocolate”. Non c'è modo di ancorarla all'inizio.
Perché vedo la stessa gerarchia più di una volta? +
Le stringhe memorizzate differiscono per spaziatura, tag (“en:chocolates” contro “Chocolates”) o lingua, e l'endpoint conta per stringa grezza. Unisci sui segmenti ripuliti per farle collassare.
Posso elencare solo le categorie USDA o solo quelle di Open Food Facts? +
No: non c'è alcun filtro per fonte e le righe non riportano la source. Recupera un prodotto della categoria con la Food Database API e leggi il suo campo source.
Posso filtrare la ricerca per categoria? +
Non con un parametro. Invia il segmento come q alla Food Search API, che ripiega sulla corrispondenza di categoria solo quando nessun nome di prodotto o marca corrisponde; filtra sul campo category di ogni risultato per una corrispondenza esatta.
total conta i prodotti o le categorie? +
Le stringhe di categoria distinte che corrispondono a q: nella risposta catturata total è 11303 per q=chocolate, mentre la sola prima riga contiene 46110 prodotti. Somma tu product_count per ottenere un totale di prodotti.
Scopri altri endpoint
API di ricerca alimenti
Ricerca full-text su 6,1 milioni di prodotti alimentari per nome, marca o categoria — ordinata per rilevanza, paginata e veloce. Cerca in qualsiasi lingua in cui sia stampata l'etichetta (cirillico incluso) e passa lang=en|fr|es|de|it|bg per nomi, categorie e allergeni localizzati. Una sola richiesta GET restituisce JSON pulito, pronto da mostrare nella tua app.
Scopri di più →API del database alimentare
Un'unica fonte per 6,1 milioni di alimenti. Recupera un record di prodotto completo tramite ID — nome, marca, ingredienti, allergeni, Nutri-Score, gruppo NOVA, immagini e altro.
Scopri di più →Inizia subito con API delle categorie alimentari
Gratis per iniziare. Nessuna carta di credito richiesta.
Ottieni la chiave API Vai alla dashboard