API JSON v1

Avaliações de alimentos para a sua aplicação

Tudo o que o site mostra está disponível em JSON. Os pedidos precisam da chave de API do servidor — envie-a num cabeçalho X-API-Key (ou Authorization: Bearer <chave>). As respostas nunca são guardadas em cache por intermediários (Cache-Control: no-store) e permitem CORS a partir de qualquer origem.

Endpoints

Exemplos

# produto por código de barras
curl -H "X-API-Key: $API_KEY" "https://maxing.fitness/api/v1/product/3017624010701"

# pesquisa em texto livre, textos em português
curl -G -H "X-API-Key: $API_KEY" --data-urlencode "q=flocos de aveia" \
  "https://maxing.fitness/api/v1/search?lang=pt"

Idiomas

Os resumos e os motivos estão em inglês por predefinição. Acrescente lang com um destes códigos para os receber noutra língua da 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. As classificações, as pontuações, os identificadores das regras e as chaves de missing são iguais em todas as línguas.

Formato da resposta

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

Classificações

Cada avaliação tem um rating (green, yellow, red ou unknown), um summary de uma linha, reasons legíveis e matches que apontam para os ingredientes (pelo índice em ingredients) que a desencadearam. missing lista os dados que melhorariam a avaliação. healthy é a resposta global: verde para produtos com o selo Buraco da fechadura (Nyckelhålet); caso contrário, o Nutri-Score (do Open Food Facts ou estimado com o algoritmo de 2023, caso em que score contém os pontos), um nível abaixo para alimentos ultraprocessados. As heurísticas estão documentadas no README; as alterações relevantes para os clientes incrementam meta.classifierVersion (também enviado no cabeçalho X-Classifier-Version).

Erros

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

Códigos de barras a partir do telemóvel

As aplicações nativas podem ler códigos com qualquer biblioteca de códigos de barras e chamar GET /api/v1/product/{gtin} com os dígitos tal como estão: EAN-8, UPC-A (12 dígitos), EAN-13 e GTIN-14 com zeros à esquerda são normalizados para o mesmo produto. Os UPC-E têm de ser primeiro expandidos para UPC-A. O leitor do próprio site faz exatamente isso no navegador.

Cache e limites de pedidos

Os produtos ficam em cache durante 30 dias por GTIN e depois são atualizados a partir das bases de dados de origem; se estas estiverem em baixo, é servida a cópia antiga. O Open Food Facts permite cerca de 15 leituras de produtos e 10 pesquisas por minuto e por IP, por isso rajadas de consultas fora da cache podem devolver 503 rate_limited — respeite Retry-After. Dados: Open Food Facts (ODbL) e Dabas.