API de categorías de alimentos
Explora todas las categorías de alimentos con su recuento de productos: la base de filtros, facetas y navegación. JSON paginado sobre todo el catálogo, servido desde una vista precalculada para que siga siendo rápido.
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
}¿Prefieres hacer clic? Prueba el explorador de productos o la zona de pruebas de fotos.
Qué obtienes
category
El nombre de la categoría.
product_count
Cuántos productos pertenecen a ella.
total
Número de categorías distintas.
Listo para filtrar
Combínalo con la búsqueda para acotar los resultados por categoría.
Incluido en el plan gratuito: 100 solicitudes/día, sin tarjeta de crédito. Ver planes →
Ejemplos de código
La misma petición en curl, JavaScript y Python. Sustituye YOUR_API_KEY por una clave de tu panel.
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()
Cómo funciona
Qué devuelve una petición
GET /v1/categories lee una tabla precalculada con cada cadena de categoría distinta del catálogo y cuántos productos la llevan; los productos sin categoría se excluyen. Las filas se ordenan por product_count descendente sin ningún orden secundario, así que no dependas del orden de las filas con el mismo recuento.
q es un filtro de subcadena sin distinguir mayúsculas, no de prefijo: q=chocolate coincide por igual con "Chocolate", "en:chocolates" y "Beverages, Dairies, Dairy drinks, Flavoured milks, Chocolate milks", y reduce la respuesta capturada a un total de 11303 cadenas distintas. Los espacios se recortan, % y _ son literales y q tiene un tope de 200 caracteres.
limit va de 1 a 100 (por defecto 20) y offset de 0 a 10000, así que con limit=100 puedes llegar como máximo a las primeras 10.100 filas; acota con q en lugar de paginar más a fondo. Las respuestas llevan Cache-Control: public, max-age=600, el servidor cachea durante una hora y la tabla solo se reconstruye en una reimportación masiva, así que obtén los datos una vez al arrancar o en un paso de compilación y guarda el resultado.
Dos formas de cadena de categoría
Los productos de Open Food Facts llevan una jerarquía unida con comas, de lo general a lo específico: "Snacks, Sweet snacks, Cocoa and its products, Chocolates, Dark chocolates". Los segmentos pueden ser etiquetas de taxonomía en bruto con un prefijo de idioma de dos letras ("en:chocolate-candies"), pueden estar en el idioma de la etiqueta ("Botanas, Snacks dulces, Cacao y sus productos, Chocolates, Chocolates negros") y a menudo terminan en un cajón de sastre como en:groceries que no es el nivel más específico.
Los productos del USDA llevan una sola categoría de venta plana cuyo nombre puede contener comas ("Chips, Pretzels & Snacks"); nunca la dividas. Las filas de aquí no llevan source, así que cuando lo necesites, obtén un producto de la categoría con la API de base de datos de alimentos y lee source junto a category y categories_tags.
Una misma jerarquía puede aparecer como varias filas: la respuesta capturada lista "Snacks, Sweet snacks, Cocoa and its products, Chocolates, Dark chocolates" (497 productos) y la misma ruta sin espacios tras las comas (339) por separado. Fusiona por segmentos limpios, no por la cadena en bruto.
Crear un árbol de navegación o una interfaz de filtros
Aplica la limpieza que usa el sitio web: divide por comas, recorta espacios, quita una etiqueta xx: inicial, sustituye los guiones por espacios, pon en mayúscula la primera letra y descarta los segmentos repetidos sin distinguir mayúsculas. El primer segmento limpio es la raíz; el último que no sea un cajón de sastre (groceries, food, foods, products, unknown, none) es la hoja. El recuento de un nodo es la suma de product_count de todas las cadenas en bruto que se asignan a él.
- Nodos raíz: agrupa por el primer segmento limpio ("Snacks", "Beverages", "Botanas").
- Chips de hoja: el último segmento que no sea un cajón de sastre ("Dark chocolates", "Chocolate milks").
- Nombres planos del USDA: la cadena entera es a la vez raíz y hoja.
- Idioma: las jerarquías en idiomas distintos siguen siendo nodos separados; para traducciones por producto, pasa lang= a la API de búsqueda de alimentos y lee category_localized y category_segments_localized.
- El árbol de navegación del sitio web en /categories/ aplica estas mismas reglas de limpieza a estos datos (y conserva solo las hojas más grandes); úsalo para comprobar tu resultado.
De una categoría a sus productos
La búsqueda no tiene parámetro de categoría. La API de búsqueda de alimentos compara primero nombres de producto y marcas y, solo cuando eso no encuentra nada, compara las palabras de tu consulta con las cadenas de categoría. Envía como q un segmento limpio completo que no sea en sí mismo un nombre de producto, como "Seeds & Related Snacks", y obtendrás los productos de esa categoría ordenados por popularidad.
El recurso de reserva se basa en palabras, así que "Seeds & Related Snacks" coincide con toda cadena de categoría que contenga esas palabras en cualquier idioma, y un segmento que también es una palabra de producto común ("Chocolate" o "Dark chocolates") nunca llega a él porque los nombres de producto coinciden primero. Para un listado estricto, filtra cada resultado por su campo category, que es la cadena en bruto que devolvió este endpoint.
Qué puedes crear
Filtros y facetas
Pinta una navegación por categorías con recuentos de productos en vivo.
Visión general del catálogo
Muestra a los usuarios la forma del conjunto de datos antes de que busquen.
Paneles de analítica
Representa en gráficos cómo se distribuyen los productos entre categorías.
Límites por plan
| Free | 100 solicitudes/día compartidas entre endpoints, 1/s (ráfaga de 5); suficiente para refrescar un árbol en caché varias veces al día. |
|---|---|
| Starter | 5000 solicitudes/día, 5/s (ráfaga de 25). |
| Pro | 25.000 solicitudes/día, 20/s (ráfaga de 100). |
| Enterprise | 100.000 solicitudes/día, 50/s (ráfaga de 250). |
Cada respuesta incluye cabeceras X-RateLimit-* con el presupuesto restante; cada 429 incluye Retry-After . Comparar planes →
Errores y cómo gestionarlos
401 — X-API-Key falta, no es válida o está revocada.
Envía una clave del panel; el campo error del cuerpo indica cuál es el caso.
422 — limit fuera de 1–100, offset fuera de 0–10000, o q con más de 200 caracteres.
Acota los valores en el cliente; aquí la validación devuelve 422, no 400.
429 — Se agotó el límite por segundo de la clave o la cuota diaria de la cuenta.
Espera a Retry-After y mientras tanto sirve tu copia en caché.
Comparada con otras API
Esto es un listado de cadenas de categoría tal como están guardadas, con recuentos, no una taxonomía curada. Los colaboradores de Open Food Facts y la importación del USDA aportan cada uno su propia forma, espaciado, idioma y etiquetas, y el endpoint no los fusiona; las reglas de limpieza de arriba te corresponde aplicarlas a ti. A cambio, los recuentos coinciden exactamente con el catálogo y cada cadena se puede devolver tal cual a la búsqueda o compararse con el campo category de un producto. Construye un único árbol normalizado a partir de esta lista y cachéalo, porque los datos solo cambian en una reimportación.
Preguntas frecuentes
¿q es una coincidencia de prefijo o de subcadena? +
Subcadena, sin distinguir mayúsculas, en cualquier parte de la cadena; q=chocolate devuelve "Beverages, Dairies, Dairy drinks, Flavoured milks, Chocolate milks" además de "Chocolate". No hay forma de anclarla al principio.
¿Por qué veo la misma jerarquía más de una vez? +
Las cadenas guardadas difieren en espaciado, etiquetado ("en:chocolates" frente a "Chocolates") o idioma, y el endpoint cuenta por cadena en bruto. Fusiona por segmentos limpios para colapsarlas.
¿Puedo listar solo las categorías del USDA o solo las de Open Food Facts? +
No: no hay filtro de fuente y las filas no llevan source. Obtén un producto de la categoría con la API de base de datos de alimentos y lee su campo source.
¿Puedo filtrar la búsqueda por categoría? +
No con un parámetro. Envía el segmento como q a la API de búsqueda de alimentos, que recurre a la coincidencia por categoría solo cuando ningún nombre de producto ni marca coincide; filtra por el campo category de cada resultado para una coincidencia exacta.
¿total cuenta productos o categorías? +
Cadenas de categoría distintas que coinciden con q: en la respuesta capturada, total es 11303 para q=chocolate mientras que la primera fila por sí sola contiene 46110 productos. Suma product_count tú mismo para obtener un total de productos.
Descubre más endpoints
API de búsqueda de alimentos
Búsqueda de texto completo en 6,1 millones de productos alimentarios por nombre, marca o categoría: ordenada por relevancia, paginada y rápida. Busca en cualquier idioma en que se imprimió la etiqueta (cirílico incluido) y pasa lang=en|fr|es|de|it|bg para obtener nombres, categorías y alérgenos localizados. Una sola petición GET devuelve un JSON limpio que tu app puede mostrar al instante.
Más información →API de base de datos de alimentos
Una única fuente para 6,1 millones de alimentos. Obtén el registro completo de un producto por ID: nombre, marca, ingredientes, alérgenos, Nutri-Score, grupo NOVA, imágenes y más.
Más información →Empieza a crear con la API de categorías de alimentos
Gratis para empezar. Sin tarjeta de crédito.
Obtener clave API Ir al panel