JSON API v1

Hodnotenia potravín pre vašu aplikáciu

Všetko, čo zobrazuje web, je dostupné aj ako JSON. Požiadavky vyžadujú kľúč API servera – pošlite ho v hlavičke X-API-Key (alebo Authorization: Bearer <kľúč>). Sprostredkovatelia odpovede nikdy neukladajú do medzipamäte (Cache-Control: no-store) a odpovede povoľujú CORS z ľubovoľného pôvodu.

Koncové body

Koncový bod	Čo robí
`GET /api/v1`	Prehľadový dokument: zapnuté zdroje, koncové body, jazyky a verzia klasifikátora.
`GET /api/v1/search?q=…`	Vyhľadávanie podľa názvu alebo kategórie (najprv Dabas, potom Open Food Facts). Ak je `q` čiarový kód, produkt sa vyhľadá priamo a vráti sa v odpovedi.
`GET /api/v1/product/{gtin}`	Produkt so zoznamom zložiek, výživovými údajmi, celkovým hodnotením `healthy` a hodnoteniami FODMAP, keto, GI a spracovania. Prijíma EAN-8, UPC-A, EAN-13 a GTIN-14 (úvodné nuly sa normalizujú).

Príklady

# produkt podľa čiarového kódu
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# fulltextové vyhľadávanie, texty v slovenčine
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=ovsené vločky" \
  "https://maxing.fitness/api/v1/search?lang=sk"

Jazyky

Zhrnutia a zdôvodnenia sú predvolene v angličtine. Pridajte lang s jedným z týchto kódov a dostanete ich v inom jazyku EÚ: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Hodnotenia, skóre, ID pravidiel a kľúče missing sú vo všetkých jazykoch rovnaké.

Formát odpovede

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

Hodnotenia

Každé hodnotenie má rating s hodnotou green, yellow, red alebo unknown, jednoriadkové zhrnutie summary, zrozumiteľné zdôvodnenia reasons a matches, ktoré ukazujú na zložky (indexom v ingredients), ktoré hodnotenie ovplyvnili. missing uvádza údaje, ktoré by hodnotenie spresnili. healthy je celková odpoveď: zelená pre produkty s označením Kľúčová dierka (Nyckelhålet), inak známka Nutri-Score (z Open Food Facts alebo odhadnutá algoritmom z roku 2023 – vtedy score obsahuje jej body), o stupeň nižšie pre ultraspracované potraviny. Heuristiky sú opísané v README; zmeny dôležité pre klientov zvyšujú meta.classifierVersion (posiela sa aj v hlavičke 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)

Čiarové kódy z mobilu

Natívne aplikácie môžu skenovať ľubovoľnou knižnicou na čiarové kódy a volať GET /api/v1/product/{gtin} so surovými číslicami: EAN-8, UPC-A (12 číslic), EAN-13 aj nulami doplnené kódy GTIN-14 sa normalizujú na ten istý produkt. UPC-E treba najprv rozšíriť na UPC-A. Skener na webe robí v prehliadači presne to isté.

Medzipamäť a limity požiadaviek

Produkty sa ukladajú do medzipamäte na 30 dní pre každý GTIN a potom sa obnovia zo zdrojových databáz; ak databázy nefungujú, vráti sa staršia uložená kópia. Open Food Facts povoľuje približne 15 načítaní produktov a 10 vyhľadávaní za minútu z jednej IP adresy, takže pri náraze neuložených dopytov môže prísť odpoveď 503 rate_limited – rešpektujte Retry-After. Údaje: Open Food Facts (ODbL) a Dabas.