API JSON v1

Des évaluations d’aliments pour votre application

Tout ce qu’affiche le site est disponible en JSON. Les requêtes nécessitent la clé d’API du serveur : envoyez-la dans un en-tête X-API-Key (ou Authorization: Bearer <clé>). Les réponses ne sont jamais mises en cache par les intermédiaires (Cache-Control: no-store) et autorisent le CORS depuis n’importe quelle origine.

Points de terminaison

Exemples

# produit par code-barres
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# recherche en texte libre, textes en français
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=flocons d'avoine" \
  "https://maxing.fitness/api/v1/search?lang=fr"

Langues

Les résumés et les justifications sont en anglais par défaut. Ajoutez lang avec l’un de ces codes pour les obtenir dans une autre langue de l’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. Les notations, les scores, les identifiants de règles et les clés missing sont les mêmes dans toutes les langues.

Structure de la réponse

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

Notations

Chaque évaluation comporte un rating (green, yellow, red ou unknown), un résumé d’une ligne (summary), des justifications lisibles (reasons) et des matches qui désignent les ingrédients (par leur index dans ingredients) à l’origine du résultat. missing liste les données qui amélioreraient l’évaluation. healthy est la réponse globale : vert pour les produits portant le logo Trou de serrure (Nyckelhålet), sinon le Nutri-Score (d’Open Food Facts, ou estimé avec l’algorithme 2023, auquel cas score contient ses points), un cran plus bas pour les aliments ultra-transformés. Les heuristiques sont documentées dans le README ; les changements notables incrémentent meta.classifierVersion (également envoyé dans l’en-tête X-Classifier-Version).

Erreurs

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

Codes-barres depuis un téléphone

Les applications natives peuvent scanner avec n’importe quelle bibliothèque de codes-barres et appeler GET /api/v1/product/{gtin} avec les chiffres bruts : EAN-8, UPC-A (12 chiffres), EAN-13 et GTIN-14 complété par des zéros sont tous normalisés vers le même produit. Un UPC-E doit d’abord être converti en UPC-A. Le lecteur du site fait exactement cela dans le navigateur.

Cache et limites de débit

Les produits sont mis en cache 30 jours par GTIN, puis actualisés depuis les bases de données sources ; si elles sont hors service, une copie ancienne est servie. Open Food Facts autorise environ 15 lectures de produits et 10 recherches par minute et par IP : des rafales de requêtes hors cache peuvent donc renvoyer 503 rate_limited – respectez Retry-After. Données : Open Food Facts (ODbL) et Dabas.