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=bg"

Езици

По подразбиране обобщенията и обосновките са на английски. Добавете 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.