API JSON v1

Valoraciones de alimentos para tu app

Todo lo que muestra la web está disponible en JSON. Las peticiones necesitan la clave de API del servidor: envíala en una cabecera X-API-Key (o Authorization: Bearer <clave>). Los intermediarios nunca guardan las respuestas en caché (Cache-Control: no-store) y se permite CORS desde cualquier origen.

Endpoints

Ejemplos

# producto por código de barras
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# búsqueda de texto libre, textos en español
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=copos de avena" \
  "https://maxing.fitness/api/v1/search?lang=es"

Idiomas

Los resúmenes y los motivos están en inglés por defecto. Añade lang con uno de estos códigos para recibirlos en otra lengua de la UE: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Las calificaciones, las puntuaciones, los identificadores de reglas y las claves de missing son iguales en todos los idiomas.

Formato de la respuesta

{
  "ok": true,
  "data": {
    "product":  { "gtin": "3017624010701", "name": "Nutella", "brand": "Ferrero", "ingredientsText": "…",
                  "nutrition": { "basis": "100g", "carbs": 57.5, "sugars": 56.3, … },
                  "novaGroup": 4, "images": { "front": "…" }, "sources": [ { "name": "off", … } ] },
    "verdicts": {
      "healthy":   { "rating": "red",    "summary": "Nutri-Score E, ultra-processed, high in sugar and saturated fat", … },
      "fodmap":    { "rating": "yellow", "summary": "…", "reasons": ["…"], "matches": [ … ] },
      "keto":      { "rating": "red",    … },
      "glycemic":  { "rating": "yellow", … },
      "processed": { "rating": "red",    … }
    },
    "ingredients": [ { "text": "socker", "depth": 0, "section": "main" }, … ],
    "traces": ["nötter"],
    "labels": [],
    "cache": { "status": "hit", "fetchedAt": "2026-08-26T18:00:00.000Z", "partial": false }
  },
  "meta": { "classifierVersion": 2, "cache": "hit", "sources": ["off"], "attribution": { … } }
}

Calificaciones

Cada valoración tiene un rating (green, yellow, red o unknown), un summary de una línea, unos reasons legibles y unos matches que señalan los ingredientes (por su índice en ingredients) que la han activado. missing enumera los datos que mejorarían la valoración. healthy es la respuesta global: verde para los productos con el sello Ojo de cerradura (Nyckelhålet); si no, el Nutri-Score (de Open Food Facts o estimado con el algoritmo de 2023, en cuyo caso score contiene sus puntos), un nivel menos para los alimentos ultraprocesados. Las heurísticas están documentadas en el README; los cambios relevantes para los clientes incrementan meta.classifierVersion (que también se envía en la cabecera X-Classifier-Version).

Errores

{ "ok": false, "error": { "code": "unauthorized", "message": "…" } }

400 invalid_gtin · 401 unauthorized · 404 product_not_found / not_found
503 api_not_configured · 503 upstream_unavailable / rate_limited (with Retry-After)

Códigos de barras desde el móvil

Las apps nativas pueden escanear con cualquier biblioteca de códigos de barras y llamar a GET /api/v1/product/{gtin} con los dígitos tal cual: EAN-8, UPC-A (12 dígitos), EAN-13 y GTIN-14 con ceros a la izquierda se normalizan al mismo producto. Los UPC-E deben expandirse antes a UPC-A. El escáner de la propia web hace exactamente eso en el navegador.

Caché y límites de peticiones

Los productos se guardan en caché 30 días por GTIN y después se actualizan desde las bases de datos de origen; si no responden, se sirve la copia antigua. Open Food Facts permite unas 15 consultas de productos y 10 búsquedas por minuto e IP, así que una ráfaga de consultas que no estén en caché puede responder 503 rate_limited: respeta Retry-After. Datos: Open Food Facts (ODbL) y Dabas.