API de Datos Nutricionales de Nutrola: Cómo los Desarrolladores Pueden Acceder a Nuestra Base de Datos de Alimentos
Una guía para desarrolladores sobre la API de Datos Nutricionales de Nutrola. Aprende cómo acceder a nuestra base de datos verificada de alimentos con más de 3 millones de entradas, explora los endpoints, la autenticación y casos de uso reales.
¿Estás construyendo una aplicación de salud, fitness o alimentación? Uno de los problemas más difíciles que enfrentarás son los datos nutricionales. Necesitas información precisa sobre calorías y macronutrientes para miles de alimentos, necesitas que cubra productos internacionales y que se mantenga actualizada a medida que los fabricantes reformulan sus productos.
La mayoría de los desarrolladores comienzan extrayendo datos de bases de datos gubernamentales abiertas como USDA FoodData Central. Eso proporciona una base, pero no cubre productos de marca de 47 países, comidas de restaurante ni los miles de alimentos regionales que los usuarios reales consumen cada día. Llenar esos vacíos por tu cuenta significa años de trabajo de curación de datos.
La API de Datos Nutricionales de Nutrola da a los desarrolladores acceso a la misma base de datos verificada de alimentos que potencia nuestra aplicación — más de 3 millones de entradas, incluyendo ingredientes crudos, productos de marca, comidas de restaurante y recetas compuestas. Cada entrada está verificada a través de nuestro proceso de control de calidad multicapa, el mismo sistema en el que confían más de 2 millones de usuarios.
Esta guía cubre todo lo que necesitas saber para comenzar a construir con nuestra API: arquitectura, autenticación, endpoints, límites de velocidad y ejemplos de código del mundo real.
Descripción General de la API
La API de Datos Nutricionales de Nutrola es una API JSON RESTful. Haces solicitudes HTTP y recibes respuestas JSON. No se requieren SDKs, aunque proporcionamos bibliotecas cliente para Python, JavaScript y Swift por conveniencia.
URL Base
https://api.nutrola.com/v1
Todos los endpoints se sirven a través de HTTPS. Las solicitudes HTTP simples son rechazadas.
Capacidades Principales
| Capacidad | Descripción |
|---|---|
| Búsqueda de Alimentos | Búsqueda de texto completo en más de 3M de entradas de alimentos con filtrado por categoría, marca y país |
| Consulta por Código de Barras | Obtén datos nutricionales por UPC, EAN u otros formatos de código de barras |
| Detalles Nutricionales | Perfil nutricional completo para cualquier alimento (más de 70 nutrientes incluyendo micronutrientes) |
| Tamaños de Porción | Tamaños de porción estándar y alternativos con conversiones en gramos |
| Análisis de Recetas | Envía una lista de ingredientes y obtén datos nutricionales combinados |
| Categorías de Alimentos | Navega por la taxonomía jerárquica de categorías de alimentos |
| Directorio de Marcas | Busca y explora fabricantes de alimentos de marca |
| Autocompletado | Sugerencias rápidas de escritura anticipada para interfaces de búsqueda de alimentos |
Formato de Respuesta
Todas las respuestas siguen una estructura consistente:
{
"status": "success",
"data": { },
"meta": {
"request_id": "req_abc123",
"rate_limit_remaining": 245,
"rate_limit_reset": "2026-03-10T15:00:00Z"
}
}
Las respuestas de error incluyen un código de error legible por máquina y un mensaje legible por humanos:
{
"status": "error",
"error": {
"code": "FOOD_NOT_FOUND",
"message": "No food entry matches the provided ID.",
"request_id": "req_xyz789"
}
}
Autenticación
Todas las solicitudes a la API requieren una clave de API enviada en el encabezado Authorization.
Obtener una Clave de API
- Crea una cuenta de desarrollador en developer.nutrola.com
- Navega a la sección de Claves de API en tu panel de control
- Genera una nueva clave y especifica los alcances que necesitas
- Almacena la clave de forma segura — solo se mostrará una vez
Usar Tu Clave de API
Incluye la clave en cada encabezado de solicitud:
Authorization: Bearer YOUR_API_KEY
Ejemplo con curl:
curl -H "Authorization: Bearer ntr_live_abc123def456" \
https://api.nutrola.com/v1/foods/search?q=chicken+breast
Alcances de la Clave de API
| Alcance | Nivel de Acceso |
|---|---|
foods:read |
Buscar y obtener datos de alimentos (más común) |
barcodes:read |
Consulta por código de barras |
recipes:analyze |
Análisis nutricional de recetas |
brands:read |
Acceso al directorio de marcas |
categories:read |
Taxonomía de categorías de alimentos |
Las claves pueden limitarse a capacidades específicas. Una clave con solo foods:read no puede acceder a consultas por código de barras. Esto sigue el principio de menor privilegio — solicita solo los alcances que tu aplicación necesita.
Endpoints Principales
Búsqueda de Alimentos
Busca en la base de datos por nombre, palabra clave o frase.
GET /v1/foods/search
Parámetros:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
q |
string | Sí | Consulta de búsqueda (ej., "grilled chicken breast") |
category |
string | No | Filtrar por categoría de alimento (ej., "dairy", "vegetables") |
brand |
string | No | Filtrar por nombre de marca |
country |
string | No | Código de país ISO 3166-1 alfa-2 (ej., "US", "DE", "JP") |
verified_only |
boolean | No | Solo devolver entradas con datos de origen verificados (por defecto: true) |
page |
integer | No | Número de página para paginación (por defecto: 1) |
per_page |
integer | No | Resultados por página, máximo 50 (por defecto: 20) |
Solicitud de Ejemplo:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.nutrola.com/v1/foods/search?q=greek+yogurt&country=US&per_page=5"
Respuesta de Ejemplo:
{
"status": "success",
"data": {
"results": [
{
"id": "food_8f2k9d",
"name": "Greek Yogurt, Plain, Nonfat",
"brand": null,
"category": "dairy",
"country": "US",
"verified": true,
"source": "USDA",
"nutrition_per_100g": {
"calories": 59,
"protein": 10.2,
"carbohydrates": 3.6,
"fat": 0.4,
"fiber": 0,
"sugar": 3.2,
"sodium": 36
},
"default_serving": {
"description": "1 container (170g)",
"grams": 170
}
}
],
"total_results": 342,
"page": 1,
"per_page": 5
}
}
Obtener Detalles de un Alimento
Recupera el perfil nutricional completo de un alimento específico.
GET /v1/foods/{food_id}
Solicitud de Ejemplo:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.nutrola.com/v1/foods/food_8f2k9d"
La respuesta de detalle incluye el desglose nutricional completo — más de 70 nutrientes incluyendo todas las vitaminas, minerales, aminoácidos y perfiles de ácidos grasos. También incluye todos los tamaños de porción disponibles y sus equivalentes en gramos.
Respuesta Parcial (Nutrientes Clave):
{
"status": "success",
"data": {
"id": "food_8f2k9d",
"name": "Greek Yogurt, Plain, Nonfat",
"nutrition_per_100g": {
"calories": 59,
"protein": 10.2,
"carbohydrates": 3.6,
"fat": 0.4,
"fiber": 0,
"sugar": 3.2,
"saturated_fat": 0.1,
"monounsaturated_fat": 0.1,
"polyunsaturated_fat": 0,
"cholesterol": 5,
"sodium": 36,
"potassium": 141,
"calcium": 110,
"iron": 0.1,
"vitamin_a": 4,
"vitamin_c": 0,
"vitamin_d": 0
},
"serving_sizes": [
{ "description": "1 container (170g)", "grams": 170 },
{ "description": "1 cup (245g)", "grams": 245 },
{ "description": "1 tbsp (15g)", "grams": 15 },
{ "description": "100g", "grams": 100 }
],
"allergens": ["milk"],
"source": "USDA",
"source_id": "170903",
"last_verified": "2026-02-15",
"confidence_score": 0.98
}
}
Consulta por Código de Barras
Busca un producto alimenticio por su código de barras.
GET /v1/barcodes/{barcode}
Formatos Soportados: UPC-A, UPC-E, EAN-13, EAN-8
Solicitud de Ejemplo:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.nutrola.com/v1/barcodes/0049000006346"
La respuesta devuelve el mismo objeto de detalle de alimento que el endpoint /foods/{food_id}, con campos adicionales específicos del código de barras como barcode_format y regional_variants (un array de IDs de alimentos para el mismo producto en diferentes países, que pueden tener formulaciones diferentes).
Análisis de Recetas
Envía una lista de ingredientes y recibe el desglose nutricional combinado.
POST /v1/recipes/analyze
Cuerpo de la Solicitud:
{
"name": "Overnight Oats",
"servings": 2,
"ingredients": [
{ "food_id": "food_3k8m2n", "grams": 160 },
{ "food_id": "food_9p4q7r", "grams": 400 },
{ "food_id": "food_1a5b8c", "grams": 60 },
{ "food_id": "food_6d2e9f", "grams": 2, "description": "pinch of salt" }
]
}
También puedes enviar ingredientes como texto para análisis automático:
{
"name": "Overnight Oats",
"servings": 2,
"ingredients_text": "160g rolled oats, 400ml whole milk, 60g peanut butter, pinch of salt"
}
Respuesta:
{
"status": "success",
"data": {
"name": "Overnight Oats",
"servings": 2,
"nutrition_per_serving": {
"calories": 425,
"protein": 18.5,
"carbohydrates": 42.3,
"fat": 21.2,
"fiber": 5.8
},
"nutrition_total": {
"calories": 850,
"protein": 37.0,
"carbohydrates": 84.6,
"fat": 42.4,
"fiber": 11.6
},
"ingredients_matched": [
{ "input": "160g rolled oats", "matched_food": "food_3k8m2n", "confidence": 0.97 },
{ "input": "400ml whole milk", "matched_food": "food_9p4q7r", "confidence": 0.99 },
{ "input": "60g peanut butter", "matched_food": "food_1a5b8c", "confidence": 0.96 },
{ "input": "pinch of salt", "matched_food": "food_6d2e9f", "confidence": 0.88 }
]
}
}
Autocompletado
Sugerencias rápidas de escritura anticipada para construir interfaces de búsqueda.
GET /v1/foods/autocomplete?q={query}
Parámetros:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
q |
string | Sí | Consulta parcial de búsqueda (mínimo 2 caracteres) |
limit |
integer | No | Máximo de resultados, 1-10 (por defecto: 5) |
country |
string | No | Priorizar resultados de este país |
Los tiempos de respuesta están optimizados para uso interactivo — normalmente por debajo de 50ms. El endpoint de autocompletado devuelve objetos de alimentos simplificados (solo ID, nombre, marca y categoría) para un renderizado rápido.
Límites de Velocidad y Precios
Plan Gratuito
El plan gratuito está diseñado para desarrollo, pruebas y aplicaciones de pequeña escala:
| Límite | Valor |
|---|---|
| Solicitudes por día | 500 |
| Solicitudes por minuto | 30 |
| Resultados de búsqueda por solicitud | 20 |
| Análisis de recetas por día | 10 |
| Consultas de código de barras por día | 100 |
Plan Growth
Para aplicaciones en producción con tráfico moderado:
| Límite | Valor |
|---|---|
| Solicitudes por día | 25.000 |
| Solicitudes por minuto | 300 |
| Resultados de búsqueda por solicitud | 50 |
| Análisis de recetas por día | 500 |
| Consultas de código de barras por día | 5.000 |
| Precio | $49/mes |
Plan Enterprise
Para aplicaciones de alto tráfico, soluciones de marca blanca y requisitos personalizados:
| Característica | Detalles |
|---|---|
| Solicitudes por día | Personalizado (normalmente 100K+) |
| Límites de velocidad | Personalizados |
| Soporte dedicado | Incluido |
| SLA | Garantía de disponibilidad del 99,9% |
| Exportaciones de datos personalizadas | Disponibles |
| Notificaciones por webhook | Disponibles para actualizaciones de datos |
| Precio | Contactar a ventas |
La información sobre límites de velocidad se incluye en cada respuesta de la API a través del objeto meta y en los encabezados de respuesta HTTP (X-RateLimit-Remaining, X-RateLimit-Reset).
Casos de Uso Reales
Aplicaciones de Fitness y Entrenamiento
Si estás construyendo una aplicación de fitness y quieres añadir seguimiento nutricional sin construir una base de datos de alimentos desde cero, la API de Nutrola es el camino más rápido. Usa los endpoints de búsqueda de alimentos y código de barras para permitir que los usuarios registren comidas, y el endpoint de análisis de recetas para entradas de comidas personalizadas.
Plataformas de Planificación de Comidas
Las aplicaciones de planificación de comidas necesitan datos nutricionales precisos para generar planes que cumplan con objetivos específicos de macros. El desglose detallado de nutrientes de la API (más de 70 nutrientes) permite la optimización precisa de planes de comidas, no solo calorías y macros sino micronutrientes, alérgenos y compatibilidad con restricciones alimentarias.
Salud y Telemedicina
Las plataformas de salud que monitorean la nutrición de los pacientes pueden integrarse con la API para proporcionar un registro preciso de alimentos dentro de sus interfaces existentes. Las fuentes de datos verificadas (USDA, EFSA, datos directos del fabricante) cumplen con los estándares de precisión requeridos para el monitoreo nutricional clínico.
Restauración y Servicios de Alimentación
Las plataformas de pedidos de restaurantes pueden usar la API para mostrar información nutricional de los elementos del menú. El endpoint de análisis de recetas es particularmente útil aquí — envía los ingredientes de un plato y obtén el desglose nutricional completo sin calcular manualmente cada elemento.
Investigación y Academia
Los investigadores en nutrición pueden usar la API para estandarizar la codificación de alimentos en estudios dietéticos. Los datos consistentes y verificados reducen el error de medición que afecta a los estudios que dependen de datos nutricionales reportados por los participantes.
Ejemplos de Código
Python: Buscar un Alimento y Obtener Detalles Nutricionales
import requests
API_KEY = "ntr_live_your_key_here"
BASE_URL = "https://api.nutrola.com/v1"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
# Buscar un alimento
search_response = requests.get(
f"{BASE_URL}/foods/search",
headers=headers,
params={"q": "chicken breast grilled", "per_page": 3}
)
results = search_response.json()["data"]["results"]
for food in results:
print(f"{food['name']} - {food['nutrition_per_100g']['calories']} cal/100g")
# Obtener detalles completos del primer resultado
food_id = results[0]["id"]
detail_response = requests.get(
f"{BASE_URL}/foods/{food_id}",
headers=headers
)
food_detail = detail_response.json()["data"]
nutrition = food_detail["nutrition_per_100g"]
print(f"\n{food_detail['name']}")
print(f"Calorías: {nutrition['calories']}")
print(f"Proteína: {nutrition['protein']}g")
print(f"Carbohidratos: {nutrition['carbohydrates']}g")
print(f"Grasa: {nutrition['fat']}g")
print(f"Tamaños de porción: {food_detail['serving_sizes']}")
JavaScript: Integración de Escaneo de Código de Barras
const API_KEY = "ntr_live_your_key_here";
const BASE_URL = "https://api.nutrola.com/v1";
async function lookupBarcode(barcode) {
const response = await fetch(
`${BASE_URL}/barcodes/${barcode}`,
{
headers: {
"Authorization": `Bearer ${API_KEY}`
}
}
);
if (!response.ok) {
if (response.status === 404) {
console.log("Producto no encontrado en la base de datos");
return null;
}
throw new Error(`Error de API: ${response.status}`);
}
const data = await response.json();
return data.data;
}
// Ejemplo de uso
const product = await lookupBarcode("0049000006346");
if (product) {
const serving = product.default_serving;
const factor = serving.grams / 100;
console.log(`${product.name} (${product.brand})`);
console.log(`Por ${serving.description}:`);
console.log(` Calorías: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
console.log(` Proteína: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
console.log(` Carbohidratos: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
console.log(` Grasa: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}
Swift: Construir un Campo de Búsqueda con Autocompletado
import Foundation
class NutrolaAPI {
private let apiKey: String
private let baseURL = "https://api.nutrola.com/v1"
init(apiKey: String) {
self.apiKey = apiKey
}
func autocomplete(query: String, limit: Int = 5) async throws -> [FoodSuggestion] {
guard query.count >= 2 else { return [] }
var components = URLComponents(string: "\(baseURL)/foods/autocomplete")!
components.queryItems = [
URLQueryItem(name: "q", value: query),
URLQueryItem(name: "limit", value: String(limit))
]
var request = URLRequest(url: components.url!)
request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
let (data, _) = try await URLSession.shared.data(for: request)
let response = try JSONDecoder().decode(AutocompleteResponse.self, from: data)
return response.data.suggestions
}
}
struct FoodSuggestion: Codable {
let id: String
let name: String
let brand: String?
let category: String
}
struct AutocompleteResponse: Codable {
let status: String
let data: AutocompleteData
}
struct AutocompleteData: Codable {
let suggestions: [FoodSuggestion]
}
Buenas Prácticas para el Manejo de Errores
La API utiliza códigos de estado HTTP estándar:
| Código de Estado | Significado | Causa Común |
|---|---|---|
| 200 | Éxito | La solicitud se completó normalmente |
| 400 | Solicitud Incorrecta | Falta un parámetro obligatorio o valor inválido |
| 401 | No Autorizado | Clave de API inválida o ausente |
| 403 | Prohibido | La clave de API carece del alcance requerido |
| 404 | No Encontrado | ID de alimento o código de barras no está en la base de datos |
| 429 | Límite de Velocidad Excedido | Demasiadas solicitudes; verifica los encabezados de límite de velocidad |
| 500 | Error del Servidor | Error interno; reintenta con retroceso exponencial |
Cuando recibes una respuesta 429, el encabezado Retry-After te indica cuántos segundos debes esperar antes de reintentar. Se recomienda encarecidamente implementar retroceso exponencial para las respuestas 429 y 500 en aplicaciones de producción.
Actualización y Frescura de los Datos
La base de datos de Nutrola se actualiza continuamente. Las entradas de productos de marca se actualizan cuando los fabricantes reportan cambios, normalmente dentro de las 48 horas. Las entradas de bases de datos gubernamentales se sincronizan trimestralmente cuando se publican nuevas versiones.
Si tu aplicación almacena en caché las respuestas de la API (lo cual recomendamos por rendimiento), sugerimos un TTL de caché de 24 horas para las respuestas de detalle de alimentos y 1 hora para los resultados de búsqueda. El campo last_verified en las respuestas de detalle de alimentos te indica cuándo se confirmó por última vez la precisión de la entrada.
Para clientes enterprise, ofrecemos notificaciones por webhook cuando se actualizan las entradas de alimentos, para que tu aplicación pueda invalidar los datos en caché de forma proactiva en lugar de esperar a que expire el TTL del caché.
Primeros Pasos
- Regístrate en developer.nutrola.com — toma menos de un minuto
- Genera una clave de API con los alcances que necesitas
- Haz tu primera solicitud usando los ejemplos de curl anteriores
- Explora la documentación interactiva en developer.nutrola.com/docs donde puedes probar los endpoints directamente en tu navegador
- Únete a la comunidad de desarrolladores en nuestro servidor de Discord para soporte, solicitudes de funciones y para ver qué están construyendo otros desarrolladores
Si tienes preguntas, encuentras problemas o quieres discutir una integración enterprise, contacta a nuestro equipo de relaciones con desarrolladores en api@nutrola.com.
Preguntas Frecuentes
¿La API de Nutrola es gratuita?
Sí, hay un plan gratuito que incluye 500 solicitudes por día. Esto es adecuado para desarrollo, pruebas y aplicaciones de pequeña escala. Para aplicaciones en producción con mayor tráfico, el plan Growth comienza en $49 al mes con 25.000 solicitudes diarias. Los planes Enterprise con límites personalizados están disponibles para casos de uso de alto tráfico.
¿Qué formatos de datos soporta la API?
La API usa exclusivamente JSON tanto para solicitudes como para respuestas. Todos los endpoints aceptan parámetros de consulta estándar para solicitudes GET y cuerpos de solicitud JSON para solicitudes POST. La codificación de las respuestas es UTF-8, lo que maneja correctamente los nombres de alimentos en todos los idiomas soportados.
¿Qué tan precisos son los datos nutricionales proporcionados por la API?
Cada entrada en la base de datos de Nutrola pasa por un proceso de verificación multicapa que incluye validación de fuentes gubernamentales, verificación cruzada de datos del fabricante, comprobación estadística impulsada por IA y revisión de expertos humanos. Nuestro estándar de precisión es del 97,4% comparado con análisis de laboratorio, frente a un promedio de la industria del 70-85% para bases de datos de contribución colectiva. Cada entrada de alimento incluye un campo confidence_score que indica nuestro nivel de certeza.
¿Puedo usar la API para construir un producto comercial?
Sí. La API está diseñada para uso comercial. El plan gratuito puede usarse para productos comerciales dentro de sus límites de velocidad. Los planes Growth y Enterprise incluyen derechos de uso comercial sin restricciones en el tipo de aplicación. Revisa los términos de servicio en developer.nutrola.com para obtener todos los detalles.
¿La API soporta alimentos de fuera de Estados Unidos?
Sí. La base de datos cubre productos de marca de 47 países y alimentos genéricos de más de 120 cocinas. Usa el parámetro country en los endpoints de búsqueda para priorizar resultados de un mercado específico. Las consultas por código de barras identifican automáticamente el producto con la formulación regional correcta.
¿Cómo manejo alimentos que no están en la base de datos?
Si una consulta por código de barras devuelve un 404, puedes recurrir a una búsqueda de texto usando el nombre del producto. Si ninguno de los enfoques encuentra el alimento, puedes enviarlo para su adición a través del portal de desarrolladores. Los alimentos enviados por socios de la API tienen prioridad para verificación y normalmente se añaden dentro de 72 horas. Los clientes enterprise pueden solicitar adiciones por lotes para catálogos de productos grandes.
¿Hay SDKs o bibliotecas cliente disponibles?
Proporcionamos bibliotecas cliente oficiales para Python (vía pip: pip install nutrola), JavaScript/TypeScript (vía npm: npm install @nutrola/api) y Swift (vía Swift Package Manager). Estas bibliotecas manejan la autenticación, los límites de velocidad, los reintentos y el análisis de respuestas. Existen bibliotecas mantenidas por la comunidad para Go, Ruby y PHP.
¿Listo para transformar tu seguimiento nutricional?
¡Únete a miles que han transformado su viaje de salud con Nutrola!
