JSON-API v1

Ruoka-arviot sovellukseesi

Kaikki, mitä sivusto näyttää, on saatavilla myös JSON-muodossa. Pyynnöt vaativat palvelimen API-avaimen – lähetä se X-API-Key-otsakkeessa (tai Authorization: Bearer <avain>). Välityspalvelimet eivät koskaan tallenna vastauksia välimuistiin (Cache-Control: no-store), ja vastaukset sallivat CORS-pyynnöt mistä tahansa alkuperästä.

Päätepisteet

Päätepiste	Mitä se tekee
`GET /api/v1`	Kuvausdokumentti: käytössä olevat lähteet, päätepisteet, kielet ja luokittelijan versio.
`GET /api/v1/search?q=…`	Haku nimellä tai kategorialla (ensin Dabas, sitten Open Food Facts). Jos `q` on viivakoodi, tuote haetaan suoraan ja palautetaan vastauksen mukana.
`GET /api/v1/product/{gtin}`	Tuote ainesosaluetteloineen ja ravintosisältöineen, kokonaisarvio `healthy` sekä FODMAP-, keto-, GI- ja prosessointiarviot. Hyväksyy EAN-8-, UPC-A-, EAN-13- ja GTIN-14-koodit (alkunollat normalisoidaan).

Esimerkit

# tuote viivakoodilla
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# vapaatekstihaku, tekstit suomeksi
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=kaurahiutale" \
  "https://maxing.fitness/api/v1/search?lang=fi"

Kielet

Yhteenvedot ja perustelut ovat oletuksena englanniksi. Lisää lang-parametri jollakin näistä koodeista, niin saat ne toisella EU-kielellä: bg, es, cs, da, de, et, el, en, fr, ga, hr, it, lv, lt, hu, mt, nl, pl, pt, ro, sk, sl, fi, sv. Arviot, pisteet, sääntöjen tunnisteet ja missing-avaimet ovat samat kaikilla kielillä.

Vastauksen rakenne

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

Arviot

Jokaisella arviolla on rating (green, yellow, red tai unknown), yhden rivin yhteenveto (summary), luettavat perustelut (reasons) ja matches, joka osoittaa arvioon vaikuttaneet ainesosat (indekseinä ingredients-luetteloon). missing luettelee tiedot, jotka tarkentaisivat arviota. healthy on kokonaisvastaus: vihreä Avaimenreikämerkin (Nyckelhålet) saaneille tuotteille, muuten Nutri-Score-luokka (Open Food Facts -palvelusta tai arvioituna vuoden 2023 algoritmilla, jolloin score sisältää sen pisteet), ja yhtä porrasta alempi ultraprosessoidulle ruoalle. Heuristiikat on kuvattu README-tiedostossa; asiakkaisiin vaikuttavat muutokset kasvattavat meta.classifierVersion-arvoa (lähetetään myös X-Classifier-Version-otsakkeena).

Virheet

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

Viivakoodit puhelimesta

Natiivisovellukset voivat skannata millä tahansa viivakoodikirjastolla ja kutsua GET /api/v1/product/{gtin} pelkillä numeroilla: EAN-8, UPC-A (12 numeroa), EAN-13 ja nollilla täydennetty GTIN-14 normalisoidaan kaikki samaksi tuotteeksi. UPC-E on ensin laajennettava UPC-A-muotoon. Sivuston oma lukija tekee juuri näin selaimessa.

Välimuisti ja käyttörajat

Tuotteet tallennetaan välimuistiin 30 päiväksi GTIN-koodikohtaisesti, minkä jälkeen ne päivitetään lähdetietokannoista; jos tietokannat eivät vastaa, palautetaan vanha kopio. Open Food Facts sallii noin 15 tuotehakua ja noin 10 hakua minuutissa IP-osoitetta kohden, joten useat peräkkäiset välimuistin ohittavat haut voivat palauttaa 503 rate_limited – noudata Retry-After-otsaketta. Tiedot: Open Food Facts (ODbL) ja Dabas.