Primeros pasos con FoodBase

Crea tu cuenta

Ve a la página de registro y crea una cuenta gratuita. No hace falta tarjeta de crédito — el plan gratuito te da 100 peticiones de API al día, de sobra para probar y hacer prototipos.

Genera una clave de API

Una vez dentro, ve a Dashboard > API Keys y haz clic en Create key. Ponle un nombre descriptivo como «My App» o «Development». La clave completa solo se muestra una vez, así que cópiala y guárdala en un lugar seguro (como un archivo .env o un gestor de contraseñas).

Tu clave se verá más o menos así: food_KV23NskbwXkKzi1yaPdPF1

Haz tu primera petición

Busca un producto alimentario por nombre:

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

La respuesta incluye los productos que coinciden con sus nombres, marcas, categorías y datos nutricionales básicos:

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

Búsqueda por código de barras

Si estás creando una app con escáner de códigos de barras, usa el endpoint de código de barras con un código EAN-13 o UPC:

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

Devuelve los detalles completos del producto, incluido un resumen nutricional con calorías, proteínas, carbohidratos, grasas, azúcares y fibra — todo por 100 g.

Obtén los nutrientes detallados

Para el desglose completo de nutrientes (más de 40 valores organizados por categoría), usa el endpoint de nutrientes. Está disponible en todos los planes — el plan Free incluye 25 desgloses al día (fíjate en la cabecera X-RateLimit-Nutrients-Remaining), los planes de pago no tienen tope:

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

La respuesta agrupa los nutrientes por categorías:

• Macros — energía (kcal/kJ), proteínas, carbohidratos, grasas, fibra, azúcares, alcohol, almidón
• Grasas — saturadas, trans, mono/poliinsaturadas, omega-3/6, colesterol
• Minerales — sodio, calcio, hierro, potasio, magnesio, zinc y más
• Vitaminas — A, C, D, E, complejo B (B1, B2, B6, B9, B12), niacina

Consultas por lotes

¿Necesitas obtener varios productos a la vez? Usa el endpoint bulk con hasta 100 IDs:

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"]}'

Los resultados se devuelven en el mismo orden que los IDs de entrada — no hace falta reordenarlos por tu parte.

Prueba los endpoints de IA

Todos los planes — incluido Free — incluyen una asignación mensual de créditos de IA (20 en Free). Alimentan los endpoints de visión y análisis: identificar un producto a partir de una foto, leer una etiqueta nutricional, analizar una comida o generar un resumen con IA en lenguaje claro de cualquier producto. Cada llamada tiene un precio fijo en créditos indicado en la documentación, y cada respuesta de IA incluye las cabeceras X-Credits-Remaining.

La forma más rápida de verlos en acción es el playground de fotos — sube una foto directamente en el navegador con tu propia clave. O llama a uno directamente:

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"}'

Límites de uso que no te estorban

Los límites por segundo son token buckets: la tasa de tu plan es la velocidad sostenida (Free = 1 petición/s) y además tienes una ráfaga de 5 veces esa cifra — así que una página que lanza varias peticiones en paralelo funciona sin problema. Cada respuesta incluye cabeceras para que tu app pueda controlar el uso:

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

Si recibes un 429, siempre lleva una cabecera Retry-After con los segundos que debes esperar hasta que se acumule el siguiente token — respétala (la mayoría de los clientes HTTP pueden hacerlo automáticamente) y volverás a recibir 200 tan rápido como lo permita el limitador. Para obtener muchos productos a la vez, POST /foods/bulk es una petición en lugar de N.

Próximos pasos

• Explora la documentación de la API para ver todos los endpoints disponibles y probarlos de forma interactiva
• Explora la base de datos tú mismo en el explorador de productos — cada página de producto muestra exactamente lo que devuelve la API
• Revisa tus estadísticas de uso para controlar tus peticiones diarias
• Mejora tu plan cuando necesites más capacidad
• Lee nuestra guía de datos nutricionales para entender la cobertura de los datos