Documentazione completa

API Documentation

Guida completa per integrare le nostre API nel tuo progetto

Prova le API nel Playground

Autenticazione

Tutte le richieste richiedono un'API Key. Includi l'header X-API-Key in ogni richiesta.

Esempio di richiesta autenticata

curl -X GET '/api/v1/foods' \
  -H 'X-API-Key: food_YOUR_API_KEY'

Nota: Usa API Key con prefisso food_ per accedere a questa API.

Endpoints

GET/api/v1/foods

Ritorna la lista di tutti gli alimenti (paginata).

Query Parameters:

  • page - Numero pagina (default: 1)
  • limit - Risultati per pagina (default: 20, max: 100)
Response
{
  "success": true,
  "data": {
    "foods": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 30,
      "pages": 2
    }
  }
}
GET/api/v1/foods/:id

Ritorna un singolo alimento per ID.

Response
{
  "success": true,
  "data": {
    "food": {
      "_id": "507f1f77bcf86cd799439011",
      "info": {
        "codiceAlimento": "162410",
        "nomeAlimento": "Grana Padano, DOP",
        "categoria": "Formaggi e latticini",
        "nomeInglese": "Cheese, Grana Padano",
        "porzione": "50 g"
      },
      "macroNutrienti": {
        "energia": 1641,
        "proteine": 33.9,
        "lipidi": 28.5,
        ...
      },
      "minerali": { ... },
      "vitamine": { ... }
    }
  }
}
GET/api/v1/foods/search

Cerca alimenti per nome.

Query Parameters:

  • q - Query di ricerca (min 2 caratteri)
  • page - Numero pagina
  • limit - Risultati per pagina
Esempio
GET /api/v1/foods/search?q=mela
GET/api/v1/foods/categories

Ritorna la lista delle categorie disponibili.

Response
{
  "success": true,
  "data": {
    "categories": ["Frutta", "Verdure", "Carne", ...]
  }
}
GET/api/v1/foods/category/:category

Ritorna gli alimenti di una specifica categoria.

Esempio
GET /api/v1/foods/category/Frutta

Schema Alimento

TypeScript Interface
{
  "_id": "string",
  "info": {
    "codiceAlimento": string,  // Codice identificativo
    "nomeAlimento": string,    // Nome alimento
    "categoria": string,       // Categoria
    "nomeInglese"?: string,    // Nome inglese
    "parteEdibile"?: string,   // Es: "100 %"
    "porzione"?: string,       // Es: "50 g"
    "url"?: string             // URL fonte
  },
  "macroNutrienti"?: {
    "acqua"?: number,          // g
    "energia"?: number,        // kJ
    "proteine"?: number,       // g
    "lipidi"?: number,         // g
    "carboidratiDisponibili"?: number,
    "zuccheriSolubili"?: number,
    "fibraTotale"?: number,
    "colesterolo"?: number     // mg
  },
  "minerali"?: {
    "sodio"?: number,          // mg
    "potassio"?: number,       // mg
    "calcio"?: number,         // mg
    "magnesio"?: number,       // mg
    "fosforo"?: number,        // mg
    "ferro"?: number,          // mg
    "zinco"?: number,          // mg
    "selenio"?: number         // mcg
  },
  "vitamine"?: {
    "tiamina"?: number,        // B1 mg
    "riboflavina"?: number,    // B2 mg
    "niacina"?: number,        // B3 mg
    "vitaminaB6"?: number,     // mg
    "vitaminaB12"?: number,    // mcg
    "vitaminaC"?: number,      // mg
    "vitaminaD"?: number,      // mcg
    "vitaminaE"?: number,      // mg
    "folati"?: number          // mcg
  },
  "acidiGrassi"?: { ... },     // Dettaglio acidi grassi
  "aminoacidi"?: { ... }       // Profilo aminoacidico
}

Rate Limiting

Il numero di richieste mensili dipende dal tuo piano. Gli header di risposta includono:

X-RateLimit-Limit- Limite massimo mensile
X-RateLimit-Remaining- Richieste rimanenti
X-RateLimit-Reset- Data reset del contatore

Quando superi il limite, riceverai un errore 429 Too Many Requests.

Codici di Errore

L'API utilizza codici HTTP standard per indicare errori:

400Bad Request - Parametri non validi
401Unauthorized - API key mancante o non valida
403Forbidden - API key non autorizzata per questo prodotto
404Not Found - Risorsa non trovata
429Too Many Requests - Limite mensile raggiunto
500Server Error - Errore interno del server

Fonti dei Dati

I dati nutrizionali forniti da questa API provengono dalle seguenti fonti:

CREA - Consiglio per la ricerca in agricoltura

Tabelle di composizione degli alimenti del Centro di Ricerca Alimenti e Nutrizione (CREA-AN). Fonte ufficiale italiana per i dati nutrizionali, riconosciuta a livello istituzionale.

alimentinutrizione.it

Nutrizionisti StronGuru PROVerificati

Alimenti aggiunti e verificati dai nutrizionisti professionisti iscritti alla piattaforma StronGuru PRO, regolarmente iscritti all'Albo dei Biologi Nutrizionisti. Ogni dato inserito viene validato per garantire accuratezza e affidabilita.

Qualita garantita: Il database viene costantemente arricchito e aggiornato grazie al contributo dei professionisti verificati StronGuru PRO, assicurando dati nutrizionali accurati e affidabili.

Attribuzione CREA: I dati nutrizionali di base provengono dalle Tabelle di Composizione degli Alimenti del CREA - Centro di ricerca Alimenti e Nutrizione. Fonte: www.alimentinutrizione.it e www.crea.gov.it/alimenti-e-nutrizione. Ultimo aggiornamento della fonte: Dicembre 2019.

Quick Start

Inizia subito ad utilizzare le nostre API in pochi semplici passi:

1

Registrati

Crea un account gratuito per ottenere la tua API key.

2

Genera API Key

Dalla dashboard, genera una chiave per il prodotto desiderato.

3

Inizia a Chiamare

Usa la tua API key nell'header X-API-Key per ogni richiesta.

Inizia Gratis