API de base de datos de alimentos

Qué hace una petición

GET /v1/foods/{id} recibe el UUID que obtuviste de una búsqueda o de una consulta por código de barras y devuelve todo el registro normalizado. No hay selección de campos ni paginación: el registro de 62ea12b8-b260-c288-5c38-3a4906f5d6dd (código de barras 5449000000996, source openfoodfacts) llega con todas las claves del esquema 200, y lo que la fuente no tiene es null en lugar de omitirse.

Autentícate con la cabecera X-API-Key. La única entrada opcional es ?lang=, uno de en, fr, es, de, it o bg. Añade category_localized, category_segments_localized y allergens_localized y deja intactas todas las demás claves, así que añadir lang más adelante nunca rompe un parser existente. Cada respuesta lleva además una cabecera X-Request-Id para citar en las solicitudes de soporte.

Nombres, ingredientes y la entrada principal

name e ingredients son arrays de {lang, text}. La primera entrada tiene lang main y refleja name_default e ingredients_default; product_lang te dice qué idioma real es. En el registro de Coca-Cola, el nombre principal es Original Taste, la entrada fr dice Coca-Cola en canette y la entrada bg dice Кока-Кола. Elige la entrada que coincida con el idioma de tu interfaz y recurre a name_default.

Espera que ingredients tenga más entradas que idiomas: Open Food Facts guarda el texto de ingredientes por variante de envase, así que el mismo lang puede aparecer más de una vez en un registro, a menudo con texto idéntico, como ocurre aquí. Deduplica por lang y conserva la primera aparición. El texto lo introducen colaboradores y se devuelve tal cual; la entrada ar de aquí contiene fragmentos de etiqueta que no son ingredientes, así que valídalo antes de convertirlo en estructuras.

Categoría, etiquetas, alérgenos y lang

category es una cadena unida con comas, de lo amplio a lo concreto: Beverages and beverages preparations,Beverages,Carbonated drinks,Sodas,Colas,pt:bebidas cafeína. Divídela por la coma; el último nivel es el más específico. categories_tags contiene los mismos niveles como etiquetas para máquinas (en:beverages, en:carbonated-drinks, en:colas) y es el valor estable para filtrar o agrupar, porque la cadena para mostrar cambia cuando los colaboradores editan el producto.

allergens y traces usan el mismo estilo de etiquetas en:milk, igual que countries (en:albania, en:austria, en:belgium) y labels. null significa que la fuente no indicó nada, no que el producto esté libre de alérgenos; este registro tiene allergens: null y traces: null, así que un aviso de alergias debería decir desconocido, no ninguno.

Con ?lang=bg la API añade category_localized como una sola cadena traducida, category_segments_localized con una entrada por nivel de la jerarquía y allergens_localized en paralelo a allergens. Un nivel o etiqueta sin entrada en el diccionario es null dentro del array, así que mantén el índice alineado con categories_tags o allergens y recurre a la etiqueta en inglés en los huecos null.

Puntuaciones, tamaño de ración y nutrientes resumidos

nutriscore es una letra minúscula (e aquí), nova_group un número (4) y ecoscore_grade una cadena que puede ser una letra o un valor centinela como not-applicable, que es lo que devuelve esta bebida. Trata los tres como anulables y no asignes not-applicable a una banda de color.

serving_size_raw y quantity son texto libre copiado de la etiqueta. serving_size_raw dice 1 can (330 ml) y sirve para mostrar; quantity dice 0kg en este registro, un error de un colaborador, así que nunca calcules el peso del envase a partir de él sin una comprobación de sensatez.

nutrition_summary da seis valores por 100 g: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g y fiber_g. Cada uno puede ser null por separado y el objeto puede ser null cuando la fuente no tiene tabla nutricional. Cubre una fila de lista o una comparación rápida; los más de 40 nutrientes completos están en la API de nutrición, en /v1/foods/{id}/nutrients con el mismo id.

Ids estables, caché y el flujo habitual

El id es determinista, derivado de la fuente y del id de producto propio de la fuente, así que el mismo producto recibe el mismo UUID en cada reimportación. Guarda los ids en tus propias tablas y vuelve a consultarlos meses después sin un paso de remapeo. barcode admite null en el esquema, así que prefiere el id al código de barras como clave de unión.

Un 200 lleva Cache-Control: public, max-age=300 y un 404 lleva max-age=60, de modo que una CDN o caché HTTP delante de tu servicio los respeta sin configuración. Si cacheas en tu propia base de datos, usa como clave id más lang, ya que las claves localizadas difieren por idioma.

El flujo habitual: obtén un id de la API de búsqueda de alimentos o de la API de consulta de códigos de barras, guárdalo y llama a este endpoint cuando una vista de detalle necesite el registro completo. Para refrescar muchos ids guardados a la vez, la API de consulta masiva de alimentos recibe una lista en una sola petición desde Starter. Las imágenes son fotos de colaboradores de Open Food Facts alojadas en images.openfoodfacts.org, y los registros de otras fuentes pueden no tener ninguna, así que muestra un marcador de posición siempre que image_url sea null.