JSON API v1

Αξιολογήσεις τροφίμων για την εφαρμογή σας

Όλα όσα δείχνει ο ιστότοπος είναι διαθέσιμα και σε JSON. Τα αιτήματα απαιτούν το κλειδί API του διακομιστή – στείλτε το στην κεφαλίδα X-API-Key (ή Authorization: Bearer <κλειδί>). Οι απαντήσεις δεν αποθηκεύονται ποτέ από ενδιάμεσους διακομιστές (Cache-Control: no-store) και επιτρέπουν CORS από οποιαδήποτε προέλευση.

Τελικά σημεία

Παραδείγματα

# προϊόν βάσει γραμμωτού κώδικα
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# αναζήτηση ελεύθερου κειμένου, κείμενα στα ελληνικά
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=νιφάδες βρώμης" \
  "https://maxing.fitness/api/v1/search?lang=el"

Γλώσσες

Οι περιλήψεις και οι αιτιολογήσεις είναι από προεπιλογή στα αγγλικά. Προσθέστε lang με έναν από αυτούς τους κωδικούς για να τις λάβετε σε άλλη γλώσσα της ΕΕ: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Οι χαρακτηρισμοί, οι βαθμολογίες, τα αναγνωριστικά κανόνων και τα κλειδιά του missing είναι ίδια σε όλες τις γλώσσες.

Μορφή απάντησης

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

Αξιολογήσεις

Κάθε αξιολόγηση έχει rating με τιμή green, yellow, red ή unknown, μια περίληψη μίας γραμμής (summary), κατανοητές αιτιολογήσεις (reasons) και matches που δείχνουν τα συστατικά (με δείκτη θέσης στο ingredients) που την προκάλεσαν. Το missing απαριθμεί στοιχεία που θα βελτίωναν την αξιολόγηση. Το healthy είναι η συνολική απάντηση: πράσινο για προϊόντα με το σήμα «Κλειδαρότρυπα» (Nyckelhålet), αλλιώς το Nutri-Score (από το Open Food Facts ή εκτίμηση με τον αλγόριθμο του 2023, οπότε το score περιέχει τους πόντους του), ένα σκαλί χαμηλότερα για υπερεπεξεργασμένα τρόφιμα. Οι κανόνες περιγράφονται στο README· οι αλλαγές που επηρεάζουν τους πελάτες αυξάνουν το meta.classifierVersion (στέλνεται και ως κεφαλίδα X-Classifier-Version).

Σφάλματα

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

Γραμμωτοί κώδικες από κινητό

Οι εφαρμογές για κινητά μπορούν να σαρώνουν με οποιαδήποτε βιβλιοθήκη γραμμωτών κωδίκων και να καλούν το GET /api/v1/product/{gtin} με τα ψηφία όπως είναι: τα EAN-8, UPC-A (12 ψηφία), EAN-13 και τα GTIN-14 με μηδενικά στην αρχή κανονικοποιούνται στο ίδιο προϊόν. Το UPC-E πρέπει πρώτα να μετατραπεί σε UPC-A. Ο σαρωτής του ιστότοπου κάνει ακριβώς αυτό μέσα στο πρόγραμμα περιήγησης.

Προσωρινή αποθήκευση και όρια αιτημάτων

Τα προϊόντα αποθηκεύονται προσωρινά για 30 ημέρες ανά GTIN και στη συνέχεια ανανεώνονται από τις βάσεις δεδομένων προέλευσης· αν αυτές δεν αποκρίνονται, επιστρέφεται το παλιό αντίγραφο. Το Open Food Facts επιτρέπει περίπου 15 αναγνώσεις προϊόντων και 10 αναζητήσεις ανά λεπτό ανά IP, οπότε πολλές διαδοχικές αναζητήσεις που δεν έχουν αποθηκευτεί μπορεί να λάβουν 503 rate_limited – τηρήστε το Retry-After. Δεδομένα: Open Food Facts (ODbL) και Dabas.