API de nutrición

Una petición, cinco grupos, por 100 g

GET /v1/foods/{id}/nutrients recibe el UUID del alimento en la ruta y nada más: sin parámetros de consulta, sin cuerpo, sin lang. El id es el mismo que devuelve cualquier otro endpoint, así que un resultado de la API de búsqueda de alimentos o de la API de consulta de códigos de barras se convierte en un desglose completo con una llamada más. Los ids son deterministas entre reimportaciones, así que puedes guardarlos y seguir llamando a esta URL.

La respuesta es un objeto plano con food_id más cinco grupos fijos: macros, fats, minerals, vitamins y other. Todas las claves están siempre presentes y todos los valores son un número o null. Contando las claves del esquema actual salen 41 campos de nutrientes, de ahí la cifra de más de 40. Las unidades van en el nombre de la clave (energy_kcal, sodium_mg, selenium_mcg, vitamin_a_iu), así que nunca necesitas una tabla de unidades aparte.

Todos los valores son por 100 g del producto tal como se vende. Para mostrar una ración, multiplica por gramos dividido entre 100. El serving_size_raw del registro del alimento es texto de etiqueta (en el registro de muestra de Coca-Cola es "1 can (330 ml)"), así que la conversión de ese texto a gramos te corresponde a ti.

• macros (10 claves) cubre energía en kcal y kJ, proteínas, hidratos de carbono, grasas, azúcares, fibra, alcohol, almidón y polioles; fats (7) añade saturadas, trans, mono- y poliinsaturadas, omega3, omega6 y cholesterol_mg
• minerals (12) va de sodium_mg y salt_g a selenium_mcg y iodine_mcg; vitamins (11) da A y D en UI, B9 y B12 en mcg y el resto en mg; other contiene added_sugars_g

Cómo leer bien los nulos y los ceros

La respuesta de muestra del alimento 62ea12b8-b260-c288-5c38-3a4906f5d6dd muestra el patrón típico de Open Food Facts: energy_kcal 42, energy_kj 180.2, carbs_g 10.6, sugars_g 10.6, added_sugars_g 5.3, ceros explícitos en proteins_g, fat_g, saturated_fat_g, sodium_mg y salt_g, y null en todo lo demás, desde fiber_g hasta todo el grupo vitamins.

Trata los dos estados de forma distinta. Un 0 es un valor que la fuente informó; un null significa que el nutriente no figura en la etiqueta o no está en la fuente. Nunca conviertas null en 0 antes de sumar la ingesta de un día, o una comida hecha con productos etiquetados parcialmente subestimará en silencio las vitaminas y los minerales. Muestra un guion o "no informado" en su lugar.

La cobertura sigue a la procedencia. Las filas con source usda_foundation o usda_sr_legacy son análisis de laboratorio del USDA y rellenan los grupos de vitaminas y minerales, por lo que la mayoría de las claves son números. Las filas con source usda (USDA Branded Foods) y las de Open Food Facts se transcriben del envase, así que son fiables para los nutrientes obligatorios de la etiqueta y a menudo null más allá de ellos. El campo source del registro del alimento te dice en qué caso estás antes de pintar la tabla.

• Muestra null como desconocido, no como cero; agrega solo las claves que no sean null en todos los elementos de la comida.
• sodium_mg y salt_g existen ambos porque las etiquetas difieren según la región; usa el que espere tu público y recurre al otro.

Cuándo necesitas realmente esta llamada

Cada registro de alimento de la API de base de datos de alimentos y cada coincidencia por código de barras ya incluye nutrition_summary con seis valores principales: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g y fiber_g. Las coincidencias de búsqueda son filas más ligeras sin él. Para el resultado de un escáner, una tarjeta de detalle o un registro rápido de calorías, ese objeto suele bastar y no cuenta como desglose de nutrientes.

Reserva /nutrients para la pantalla de detalle o para el momento en que un usuario pregunta por el sodio, las grasas saturadas, el colesterol o una vitamina concreta. Busca o escanea, muestra el resumen y obtén el desglose al tocar. En el plan gratuito, esto es también lo que te mantiene dentro de la asignación de 25 al día mientras desarrollas.

Las cabeceras de la respuesta capturada no llevan Cache-Control, así que el caché es cosa tuya. Los ids son estables y los valores solo cambian cuando se reimporta un producto, por lo que una caché con clave food_id y retenida durante horas o días es segura.

La asignación del plan gratuito, cabecera por cabecera

En el plan gratuito, cada desglose correcto descuenta de un contador diario aparte de 25, informado en cada respuesta como X-RateLimit-Nutrients-Limit, X-RateLimit-Nutrients-Remaining y X-RateLimit-Nutrients-Reset. Lee Remaining antes de una ráfaga de consultas de detalle y podrás recurrir a nutrition_summary en lugar de toparte con el muro a mitad de sesión.

Al llegar a cero, el endpoint devuelve 429 con el error "Nutrients daily allowance exceeded", un upgrade_url en el cuerpo y Retry-After con los segundos hasta medianoche UTC. Una llamada rechazada no consume ni un desglose ni una solicitud diaria, y no mueve el reinicio. Los planes de pago no tienen ese contador; sus llamadas de nutrientes están limitadas solo por la cuota diaria de solicitudes del plan (compartida entre todas las claves de la cuenta) y el límite por segundo de cada clave.

Si estás en Starter o superior y trabajas con un catálogo grande, obtén primero los registros base con la API de consulta masiva de alimentos y llama a /nutrients solo para los ids cuyo resumen no baste.