JSON API v1

Hodnocení potravin pro vaši aplikaci

Vše, co web zobrazuje, je k dispozici i jako JSON. Požadavky vyžadují API klíč serveru – pošlete ho v hlavičce X-API-Key (nebo Authorization: Bearer <klíč>). Odpovědi nikdy neukládají do mezipaměti žádní prostředníci (Cache-Control: no-store) a povolují CORS z libovolného původu.

Endpointy

Příklady

# produkt podle čárového kódu
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# fulltextové hledání, texty v češtině
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=ovesné vločky" \
  "https://maxing.fitness/api/v1/search?lang=cs"

Jazyky

Shrnutí a zdůvodnění jsou ve výchozím nastavení v angličtině. Přidejte lang s jedním z těchto kódů a dostanete je v jiném jazyce EU: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Hodnocení, skóre, ID pravidel a klíče missing jsou ve všech jazycích stejné.

Struktura odpovědi

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

Hodnocení

Každé hodnocení má rating s hodnotou green, yellow, red nebo unknown, jednořádkové shrnutí summary, čitelná zdůvodnění reasons a matches, které ukazují na složky (indexem do ingredients), jež hodnocení ovlivnily. missing vypisuje údaje, které by hodnocení zpřesnily. healthy je celková odpověď: zelená pro výrobky se značkou Klíčová dírka (Nyckelhålet), jinak Nutri-Score (z Open Food Facts nebo odhad algoritmem z roku 2023 – pak score obsahuje jeho body), o stupeň níž u ultrazpracovaných potravin. Heuristiky jsou popsané v README; změny podstatné pro klienty zvyšují meta.classifierVersion (posílá se i v hlavičce X-Classifier-Version).

Chyby

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

Čárové kódy z telefonu

Nativní aplikace mohou skenovat libovolnou knihovnou pro čárové kódy a volat GET /api/v1/product/{gtin} se samotnými číslicemi: EAN-8, UPC-A (12 číslic), EAN-13 i nulami doplněný GTIN-14 se normalizují na stejný produkt. UPC-E je potřeba nejdřív rozvinout na UPC-A. Skener na webu dělá v prohlížeči přesně tohle.

Mezipaměť a limity požadavků

Produkty se ukládají do mezipaměti na 30 dní pro každý GTIN a pak se obnovují ze zdrojových databází; když databáze nefungují, vrátí se zastaralá kopie. Open Food Facts povoluje zhruba 15 načtení produktu a 10 hledání za minutu z jedné IP adresy, takže série požadavků mimo mezipaměť může skončit 503 rate_limited – respektujte Retry-After. Data: Open Food Facts (ODbL) a Dabas.