API JSON v1

Valutazzjonijiet tal-ikel għall-app tiegħek

Kull ma juri s-sit huwa disponibbli wkoll bħala JSON. It-talbiet jeħtieġu ċ-ċavetta tal-API tas-server – ibgħatha bħala header X-API-Key (jew Authorization: Bearer <ċavetta>). It-tweġibiet qatt ma jinħażnu fil-cache mill-intermedjarji (Cache-Control: no-store) u jippermettu CORS minn kull oriġini.

Endpoints

Endpoint	X'jagħmel
`GET /api/v1`	Dokument ta' skoperta: is-sorsi attivi, l-endpoints, il-lingwi u l-verżjoni tal-klassifikatur.
`GET /api/v1/search?q=…`	Tfittxija b'isem jew kategorija (l-ewwel Dabas, imbagħad Open Food Facts). Jekk `q` huwa barcode, il-prodott jinstab direttament u jintbagħat fl-istess tweġiba.
`GET /api/v1/product/{gtin}`	Il-prodott bil-lista tal-ingredjenti, il-valuri nutrizzjonali, il-valutazzjoni ġenerali `healthy` u l-valutazzjonijiet tal-FODMAP, keto, GI u proċessar. Jaċċetta EAN-8, UPC-A, EAN-13 u GTIN-14 (iż-żerijiet fil-bidu jiġu normalizzati).

Eżempji

# prodott skont il-barcode
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# tfittxija b'test ħieles, testi bil-Malti
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=porridge oats" \
  "https://maxing.fitness/api/v1/search?lang=mt"

Lingwi

Is-sommarji u r-raġunijiet huma awtomatikament bl-Ingliż. Żid lang b'wieħed minn dawn il-kodiċi biex tiksibhom f'lingwa oħra tal-UE: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Il-klassifikazzjonijiet, il-punteġġi, l-identifikaturi tar-regoli u ċ-ċwievet missing huma l-istess f'kull lingwa.

Struttura tat-tweġiba

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

Klassifikazzjonijiet

Kull valutazzjoni għandha rating ta' green, yellow, red jew unknown, sommarju ta' linja waħda (summary), raġunijiet li jinftiehmu (reasons) u matches li jindikaw l-ingredjenti (bl-indiċi tagħhom f'ingredients) li qanqluha. missing jelenka d-data li ttejjeb il-valutazzjoni. healthy hija t-tweġiba ġenerali: aħdar għall-prodotti bit-Toqba taċ-Ċavetta (Nyckelhålet), inkella n-Nutri-Score (minn Open Food Facts, jew stmat bl-algoritmu tal-2023, u f'dak il-każ score fih il-punti), pass wieħed 'l isfel għall-ikel ultraproċessat. L-euristika hija dokumentata fir-README; il-bidliet importanti jżidu meta.classifierVersion (mibgħut ukoll bħala l-header X-Classifier-Version).

Żbalji

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

Barcodes mill-mowbajl

L-apps native jistgħu jiskennjaw b'kwalunkwe librerija tal-barcodes u jsejħu GET /api/v1/product/{gtin} biċ-ċifri kif inhuma: EAN-8, UPC-A (12-il ċifra), EAN-13 u GTIN-14 mimli b'żerijiet jiġu kollha normalizzati għall-istess prodott. Kodiċi UPC-E irid jiġi estiż l-ewwel għal UPC-A. L-iskaner tas-sit jagħmel eżatt hekk fil-browser.

Cache u limiti tar-rata

Il-prodotti jinżammu fil-cache għal 30 jum għal kull GTIN, imbagħad jiġu aġġornati mill-bażijiet tad-data tas-sors; jekk dawn ma jkunux disponibbli, tintbagħat kopja qadima. Open Food Facts jippermetti madwar 15-il qari ta' prodotti u 10 tfittxijiet kull minuta għal kull IP, għalhekk ħafna talbiet f'daqqa li mhumiex fil-cache jistgħu jirċievu 503 rate_limited – irrispetta Retry-After. Data: Open Food Facts (ODbL) u Dabas.