API JSON v1

Evaluări alimentare pentru aplicația ta

Tot ce afișează site-ul este disponibil și ca JSON. Cererile necesită cheia API a serverului – trimite-o în antetul X-API-Key (sau Authorization: Bearer <cheie>). Răspunsurile nu sunt niciodată stocate în cache de intermediari (Cache-Control: no-store) și permit CORS de la orice origine.

Endpointuri

Exemple

# produs după codul de bare
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# căutare liberă, texte în română
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=fulgi de ovăz" \
  "https://maxing.fitness/api/v1/search?lang=ro"

Limbi

Rezumatele și motivele sunt implicit în engleză. Adaugă lang cu unul dintre aceste coduri ca să le primești în altă limbă a 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. Evaluările, scorurile, id-urile regulilor și cheile missing sunt aceleași în toate limbile.

Structura răspunsului

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

Evaluări

Fiecare evaluare are un rating cu valoarea green, yellow, red sau unknown, un rezumat pe un rând (summary), motive ușor de citit (reasons) și matches, care indică ingredientele (prin indexul lor în ingredients) care au declanșat-o. missing enumeră datele care ar îmbunătăți evaluarea. healthy este răspunsul general: verde pentru produsele cu simbolul „Gaura cheii” (Nyckelhålet), altfel Nutri-Score (de pe Open Food Facts sau estimat cu algoritmul din 2023, caz în care score conține punctajul), cu o treaptă mai jos pentru alimentele ultraprocesate. Euristicile sunt descrise în README; modificările importante incrementează meta.classifierVersion (trimis și în antetul X-Classifier-Version).

Erori

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

Coduri de bare de pe telefon

Aplicațiile native pot scana cu orice bibliotecă de coduri de bare și pot apela GET /api/v1/product/{gtin} cu cifrele ca atare: EAN-8, UPC-A (12 cifre), EAN-13 și GTIN-14 completat cu zerouri sunt toate normalizate la același produs. UPC-E trebuie mai întâi extins la UPC-A. Scanerul site-ului face exact asta în browser.

Cache și limite de cereri

Produsele sunt păstrate în cache 30 de zile per GTIN, apoi sunt reîmprospătate din bazele de date sursă; dacă acestea nu răspund, se servește o copie veche. Open Food Facts permite ~15 citiri de produse și ~10 căutări pe minut per IP, așa că rafalele de căutări care nu sunt în cache pot primi 503 rate_limited – respectă Retry-After. Date: Open Food Facts (ODbL) și Dabas.