JSON API v1

Maisto įvertinimai jūsų programėlei

Viskas, ką rodo svetainė, pasiekiama ir JSON formatu. Užklausoms reikia serverio API rakto – siųskite jį X-API-Key antraštėje (arba Authorization: Bearer <raktas>). Tarpiniai serveriai atsakymų niekada nesaugo talpykloje (Cache-Control: no-store), o CORS užklausos leidžiamos iš bet kurios svetainės.

Galiniai taškai

Galinis taškas	Paskirtis
`GET /api/v1`	Aprašo dokumentas: įjungti šaltiniai, galiniai taškai, kalbos ir klasifikatoriaus versija.
`GET /api/v1/search?q=…`	Paieška pagal pavadinimą ar kategoriją (pirmiausia Dabas, tada Open Food Facts). Jei `q` yra brūkšninis kodas, produktas ieškomas tiesiogiai ir grąžinamas atsakyme.
`GET /api/v1/product/{gtin}`	Produktas su sudedamųjų dalių sąrašu, maistine verte, bendru įvertinimu `healthy` ir FODMAP, keto, GI bei perdirbimo įvertinimais. Priimami EAN-8, UPC-A, EAN-13 ir GTIN-14 (pradiniai nuliai normalizuojami).

Pavyzdžiai

# produktas pagal brūkšninį kodą
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# laisvo teksto paieška, tekstai lietuvių kalba
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=avižiniai dribsniai" \
  "https://maxing.fitness/api/v1/search?lang=lt"

Kalbos

Santraukos ir paaiškinimai pagal numatytuosius nustatymus pateikiami anglų kalba. Pridėkite lang su vienu iš šių kodų, kad gautumėte juos kita ES kalba: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Įvertinimai, balai, taisyklių ID ir missing raktai visomis kalbomis vienodi.

Atsakymo struktūra

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

Įvertinimai

Kiekvienas įvertinimas turi rating (green, yellow, red arba unknown), vienos eilutės santrauką summary, žmogui suprantamus paaiškinimus reasons ir matches, nurodančius sudedamąsias dalis (pagal indeksą sąraše ingredients), kurios lėmė įvertinimą. missing išvardija duomenis, kurie padėtų patikslinti įvertinimą. healthy – bendras atsakymas: žalia produktams su simboliu „Rakto skylutė“ (Nyckelhålet), kitais atvejais – Nutri-Score (iš Open Food Facts arba apskaičiuotas 2023 m. algoritmu; tada score pateikia jo taškus), viena pakopa žemiau ultraperdirbtam maistui. Euristikos aprašytos README; reikšmingi pakeitimai padidina meta.classifierVersion (ši reikšmė siunčiama ir kaip antraštė X-Classifier-Version).

Klaidos

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

Brūkšniniai kodai iš telefono

Programėlės gali nuskaityti kodą bet kuria brūkšninių kodų biblioteka ir iškviesti GET /api/v1/product/{gtin} su neapdorotais skaitmenimis: EAN-8, UPC-A (12 skaitmenų), EAN-13 ir nuliais papildytas GTIN-14 normalizuojami į tą patį produktą. UPC-E pirmiausia reikia išplėsti į UPC-A. Pačios svetainės skaitytuvas naršyklėje daro būtent tai.

Talpykla ir užklausų ribos

Produktai talpykloje saugomi 30 dienų pagal GTIN, vėliau atnaujinami iš šaltinių duomenų bazių; jei duomenų bazės neveikia, pateikiama pasenusi kopija. Open Food Facts leidžia apie 15 produktų užklausų ir apie 10 paieškų per minutę iš vieno IP adreso, todėl staigus užklausų, kurių nėra talpykloje, antplūdis gali gauti atsakymą 503 rate_limited – paisykite Retry-After. Duomenys: Open Food Facts (ODbL) ir Dabas.