JSON API v1

Ocjene hrane za vašu aplikaciju

Sve što prikazuje web-stranica dostupno je i kao JSON. Za zahtjeve je potreban API-ključ poslužitelja – pošaljite ga u zaglavlju X-API-Key (ili kao Authorization: Bearer <ključ>). Posrednici nikad ne spremaju odgovore u predmemoriju (Cache-Control: no-store), a CORS je dopušten sa svih izvora.

Krajnje točke

Primjeri

# proizvod prema barkodu
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# pretraživanje slobodnim tekstom, tekstovi na hrvatskom
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=zobene pahuljice" \
  "https://maxing.fitness/api/v1/search?lang=hr"

Jezici

Sažeci i obrazloženja zadano su na engleskom. Dodajte lang s jednim od ovih kodova da biste ih dobili na drugom jeziku EU-a: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Ocjene, bodovi, identifikatori pravila i ključevi missing jednaki su na svim jezicima.

Struktura odgovora

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

Ocjene

Svaka ocjena ima rating (green, yellow, red ili unknown), sažetak u jednom retku (summary), čitljiva obrazloženja (reasons) i matches, koji upućuju na sastojke (indeksom u ingredients) zbog kojih je ocjena takva. missing navodi podatke koji bi poboljšali ocjenu. healthy je ukupni odgovor: zeleno za proizvode s oznakom Ključanica (Nyckelhålet), inače Nutri-Score (s Open Food Facts ili procijenjen algoritmom iz 2023. godine, a tada score sadrži njegove bodove), jedan stupanj niže za ultraprerađenu hranu. Heuristike su opisane u README-u; promjene važne za klijente povećavaju meta.classifierVersion (šalje se i kao zaglavlje X-Classifier-Version).

Pogreške

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

Barkodovi s mobitela

Izvorne aplikacije mogu skenirati bilo kojom bibliotekom za barkodove i pozvati GET /api/v1/product/{gtin} s neobrađenim znamenkama: EAN-8, UPC-A (12 znamenki), EAN-13 i GTIN-14 dopunjen nulama normaliziraju se na isti proizvod. UPC-E najprije treba proširiti u UPC-A. Skener same web-stranice radi upravo to u pregledniku.

Predmemorija i ograničenja zahtjeva

Proizvodi se spremaju u predmemoriju na 30 dana po GTIN-u, a zatim se osvježavaju iz izvornih baza podataka; ako baze nisu dostupne, poslužuje se stara kopija. Open Food Facts dopušta oko 15 čitanja proizvoda i oko 10 pretraživanja u minuti po IP-adresi, pa nalet upita koji nisu u predmemoriji može vratiti 503 rate_limited – poštujte Retry-After. Podaci: Open Food Facts (ODbL) i Dabas.