JSON API v1

Ocene živil za vašo aplikacijo

Vse, kar prikazuje spletno mesto, je na voljo tudi kot JSON. Zahteve potrebujejo ključ API strežnika – pošljite ga v glavi X-API-Key (ali Authorization: Bearer <ključ>). Posredniki odgovorov nikoli ne predpomnijo (Cache-Control: no-store), CORS pa je dovoljen z vseh izvorov.

Končne točke

Primeri

# izdelek po črtni kodi
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# iskanje po prostem besedilu, besedila v slovenščini
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=ovseni kosmiči" \
  "https://maxing.fitness/api/v1/search?lang=sl"

Jeziki

Povzetki in utemeljitve so privzeto v angleščini. Dodajte lang z eno od teh kod, pa jih boste dobili v drugem jeziku 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. Ocene, točke, ID-ji pravil in ključi missing so v vseh jezikih enaki.

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

Ocene

Vsaka ocena ima rating z vrednostjo green, yellow, red ali unknown, enovrstični povzetek summary, berljive utemeljitve reasons in matches, ki kažejo na sestavine (z indeksom v ingredients), ki so vplivale na oceno. missing navaja podatke, ki bi izboljšali oceno. healthy je skupni odgovor: zeleno za izdelke z oznako Ključavnica (Nyckelhålet), sicer ocena Nutri-Score (z Open Food Facts ali izračunana z algoritmom iz leta 2023 – takrat score vsebuje njene točke), za stopnjo nižje za ultrapredelana živila. Hevristike so opisane v datoteki README; spremembe, pomembne za odjemalce, povečajo meta.classifierVersion (pošlje se tudi v glavi X-Classifier-Version).

Napake

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

Črtne kode s telefona

Izvorne aplikacije lahko skenirajo s katero koli knjižnico za črtne kode in pokličejo GET /api/v1/product/{gtin} s surovimi števkami: EAN-8, UPC-A (12 števk), EAN-13 in z ničlami dopolnjene kode GTIN-14 se normalizirajo v isti izdelek. UPC-E je treba najprej razširiti v UPC-A. Bralnik na spletnem mestu v brskalniku naredi prav to.

Predpomnjenje in omejitve zahtev

Izdelki se za vsak GTIN hranijo v predpomnilniku 30 dni, nato se osvežijo iz izvornih baz podatkov; če baze ne delujejo, se vrne zastarela kopija. Open Food Facts dovoli približno 15 branj izdelkov in 10 iskanj na minuto na naslov IP, zato lahko val nepredpomnjenih poizvedb vrne 503 rate_limited – upoštevajte Retry-After. Podatki: Open Food Facts (ODbL) in Dabas.