JSON API v1

Élelmiszer-értékelések az alkalmazásodhoz

Minden, amit a webhely mutat, JSON formátumban is elérhető. A kérésekhez a szerver API-kulcsa szükséges – küldd el X-API-Key fejlécként (vagy Authorization: Bearer <kulcs> formában). A válaszokat a köztes szerverek soha nem gyorsítótárazzák (Cache-Control: no-store), és bármely forrásból engedélyezik a CORS-t.

Végpontok

Végpont	Mire való
`GET /api/v1`	Leíró dokumentum: engedélyezett források, végpontok, nyelvek és az osztályozó verziója.
`GET /api/v1/search?q=…`	Keresés név vagy kategória szerint (előbb Dabas, aztán Open Food Facts). Ha a `q` vonalkód, a terméket közvetlenül lekérdezzük, és a válaszban adjuk vissza.
`GET /api/v1/product/{gtin}`	Termék összetevőlistával, tápértékadatokkal, az összesített `healthy` értékeléssel, valamint a FODMAP-, keto-, GI- és feldolgozottsági értékeléssel. EAN-8, UPC-A, EAN-13 és GTIN-14 kódot is elfogad (a vezető nullákat normalizáljuk).

Példák

# termék vonalkód alapján
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# szabad szöveges keresés, magyar nyelvű szövegekkel
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=zabpehely" \
  "https://maxing.fitness/api/v1/search?lang=hu"

Nyelvek

Az összefoglalók és az indoklások alapértelmezés szerint angolul jelennek meg. Add hozzá a lang paramétert az alábbi kódok egyikével, ha másik uniós nyelven szeretnéd őket: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Az értékelések, a pontszámok, a szabályazonosítók és a missing kulcsai minden nyelven azonosak.

A válasz szerkezete

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

Értékelések

Minden értékelésnek van egy rating mezője (green, yellow, red vagy unknown), egy egysoros összefoglalója (summary), ember által olvasható indoklásai (reasons) és matches elemei, amelyek a kiváltó összetevőkre mutatnak (az ingredients tömbbeli indexükkel). A missing azokat az adatokat sorolja fel, amelyek pontosítanák az értékelést. A healthy az összesített válasz: zöld a Kulcslyuk (Nyckelhålet) jelölésű termékeknél, egyébként a Nutri-Score (az Open Food Facts adatai szerint, vagy a 2023-as algoritmussal becsülve – ekkor a score tartalmazza a pontjait), ultrafeldolgozott élelmiszernél egy fokozattal rosszabb. A heurisztikák leírása a README-ben található; a lényeges változások növelik a meta.classifierVersion értékét (ezt az X-Classifier-Version fejléc is tartalmazza).

Hibák

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

Vonalkódok telefonról

A natív alkalmazások bármilyen vonalkódkönyvtárral beolvashatják a kódot, majd meghívhatják a GET /api/v1/product/{gtin} végpontot a nyers számjegyekkel: az EAN-8, az UPC-A (12 számjegy), az EAN-13 és a nullákkal kiegészített GTIN-14 mind ugyanarra a termékre normalizálódik. Az UPC-E kódot előbb UPC-A formátumra kell bővíteni. A webhely saját olvasója is pontosan ezt teszi a böngészőben.

Gyorsítótár és kéréskorlátok

A termékeket GTIN-enként 30 napig gyorsítótárazzuk, utána frissítjük a forrásadatbázisokból; ha az adatbázisok nem érhetők el, a régi másolatot szolgáljuk ki. Az Open Food Facts IP-címenként percenként kb. 15 termékolvasást és kb. 10 keresést enged, így a sok, gyorsítótárban nem szereplő lekérdezés egymás után 503 rate_limited választ adhat – vedd figyelembe a Retry-After fejlécet. Adatok: Open Food Facts (ODbL) és Dabas.