API JSON v1

Valutazioni degli alimenti per la tua app

Tutto ciò che mostra il sito è disponibile anche in JSON. Per le richieste serve la chiave API del server: inviala nell’intestazione X-API-Key (oppure Authorization: Bearer <chiave>). Le risposte non vengono mai memorizzate nella cache da intermediari (Cache-Control: no-store) e consentono CORS da qualsiasi origine.

Endpoint

Esempi

# prodotto tramite codice a barre
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# ricerca libera, testi in italiano
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=fiocchi d'avena" \
  "https://maxing.fitness/api/v1/search?lang=it"

Lingue

Riepiloghi e motivazioni sono in inglese per impostazione predefinita. Aggiungi lang con uno di questi codici per riceverli in un’altra lingua dell’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. Valutazioni, punteggi, id delle regole e chiavi missing sono gli stessi in tutte le lingue.

Struttura della risposta

{
  "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": { … } }
}

Valutazioni

Ogni valutazione ha un rating (green, yellow, red o unknown), un riepilogo di una riga (summary), motivazioni leggibili (reasons) e matches che indicano gli ingredienti (tramite l’indice in ingredients) che l’hanno determinata. missing elenca i dati che migliorerebbero la valutazione. healthy è la risposta complessiva: verde per i prodotti con il marchio Buco della serratura (Nyckelhålet), altrimenti il Nutri-Score (da Open Food Facts, o stimato con l’algoritmo del 2023, nel qual caso score ne contiene i punti), un livello più in basso per gli alimenti ultra-processati. Le euristiche sono documentate nel README; le modifiche rilevanti incrementano meta.classifierVersion (inviato anche nell’intestazione X-Classifier-Version).

Errori

{ "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)

Codici a barre da smartphone

Le app native possono scansionare con qualsiasi libreria per codici a barre e chiamare GET /api/v1/product/{gtin} con le cifre così come sono: EAN-8, UPC-A (12 cifre), EAN-13 e GTIN-14 con zeri iniziali vengono tutti normalizzati sullo stesso prodotto. Un UPC-E va prima espanso in UPC-A. Lo scanner del sito fa esattamente questo nel browser.

Cache e limiti di frequenza

I prodotti restano in cache per 30 giorni per GTIN e poi vengono aggiornati dai database di origine; se i database non rispondono, viene servita una copia non aggiornata. Open Food Facts consente circa 15 letture di prodotti e 10 ricerche al minuto per IP, quindi raffiche di richieste non in cache possono rispondere 503 rate_limited – rispetta Retry-After. Dati: Open Food Facts (ODbL) e Dabas.