JSON-API v1

Toiduhinnangud sinu rakendusele

Kõik, mida veebisait näitab, on saadaval ka JSON-vormingus. Päringud vajavad serveri API-võtit – saada see päises X-API-Key (või Authorization: Bearer <võti>). Vahendajad ei salvesta vastuseid kunagi vahemällu (Cache-Control: no-store) ja vastused lubavad CORS-i igast päritolust.

Lõpp-punktid

Lõpp-punkt	Mida see teeb
`GET /api/v1`	Ülevaatedokument: kasutusel olevad allikad, lõpp-punktid, keeled ja klassifikaatori versioon.
`GET /api/v1/search?q=…`	Otsing nime või kategooria järgi (kõigepealt Dabas, siis Open Food Facts). Kui `q` on vöötkood, otsitakse toode otse üles ja tagastatakse kohe vastuses.
`GET /api/v1/product/{gtin}`	Toode koos koostisosade loetelu, toitumisalase teabe, üldhinnangu `healthy` ning FODMAP-i, keto, GI ja töötlemisastme hinnangutega. Sobivad EAN-8, UPC-A, EAN-13 ja GTIN-14 (algusnullid normaliseeritakse).

Näited

# toode vöötkoodi järgi
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# vabatekstiotsing, tekstid eesti keeles
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=kaerahelbed" \
  "https://maxing.fitness/api/v1/search?lang=et"

Keeled

Kokkuvõtted ja põhjendused on vaikimisi inglise keeles. Lisa parameeter lang ühega neist koodidest, et saada need mõnes teises ELi keeles: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Hinnangud, punktid, reeglite ID-d ja missing-võtmed on kõigis keeltes samad.

Vastuse struktuur

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

Hinnangud

Igal hinnangul on rating (green, yellow, red või unknown), üherealine kokkuvõte (summary), loetavad põhjendused (reasons) ning matches, mis osutab hinnangu põhjustanud koostisosadele (indeksina massiivis ingredients). missing loetleb andmed, mis teeksid hinnangu täpsemaks. healthy on üldvastus: roheline Võtmeaugu märgisega (Nyckelhålet) toodetele, muul juhul Nutri-Score (andmebaasist Open Food Facts või arvutatud 2023. aasta algoritmiga – sel juhul on score väärtuseks selle punktid), ülitöödeldud toidu puhul ühe astme võrra madalam. Heuristikad on kirjeldatud README-failis; kliente mõjutavad muudatused suurendavad väärtust meta.classifierVersion (saadetakse ka päisena X-Classifier-Version).

Vead

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

Vöötkoodid telefonist

Rakendused võivad skannida mis tahes vöötkooditeegiga ja teha päringu GET /api/v1/product/{gtin} toorete numbritega: EAN-8, UPC-A (12 numbrit), EAN-13 ja nullidega täidetud GTIN-14 normaliseeritakse kõik samaks tooteks. UPC-E tuleb enne laiendada UPC-A-ks. Veebisaidi enda lugeja teeb brauseris täpselt sedasama.

Vahemälu ja päringupiirangud

Tooted salvestatakse vahemällu 30 päevaks GTIN-i kohta ja seejärel uuendatakse lähteandmebaasidest; kui andmebaasid ei vasta, kasutatakse aegunud koopiat. Open Food Facts lubab umbes 15 tootepäringut ja 10 otsingut minutis IP-aadressi kohta, nii et paljud järjestikused vahemälust mööduvad päringud võivad saada vastuseks 503 rate_limited – järgi päist Retry-After. Andmed: Open Food Facts (ODbL) ja Dabas.