Nutrola Nutrition Data API: Come gli sviluppatori possono accedere al nostro database alimentare

Stai costruendo un'app per la salute, il fitness o il cibo? Uno dei problemi più complessi che dovrai affrontare è la gestione dei dati nutrizionali. Hai bisogno di informazioni accurate su calorie e macronutrienti per migliaia di alimenti, che coprano prodotti internazionali e che siano sempre aggiornate, man mano che i produttori riformulano i loro prodotti.

La maggior parte degli sviluppatori inizia estraendo dati da database governativi aperti come USDA FoodData Central. Questo ti fornisce una base, ma non copre i prodotti di marca provenienti da 47 paesi, i pasti dei ristoranti o i migliaia di alimenti regionali che gli utenti reali consumano ogni giorno. Colmare queste lacune da solo significa anni di lavoro di curatela dei dati.

L'API Nutrola Nutrition Data offre agli sviluppatori l'accesso allo stesso database alimentare verificato che alimenta la nostra app: oltre 3 milioni di voci, che coprono ingredienti freschi, prodotti di marca, pasti dei ristoranti e ricette composite. Ogni voce è verificata attraverso il nostro processo di controllo qualità multilivello, lo stesso sistema di cui si fidano oltre 2 milioni di utenti.

Questa guida copre tutto ciò che devi sapere per iniziare a lavorare con la nostra API: architettura, autenticazione, endpoint, limiti di richiesta e esempi di codice reali.

Panoramica dell'API

L'API Nutrola Nutrition Data è un'API RESTful JSON. Effettui richieste HTTP e ricevi risposte in JSON. Non sono richiesti SDK, anche se forniamo librerie client per Python, JavaScript e Swift per comodità.

URL Base

https://api.nutrola.com/v1

Tutti gli endpoint sono serviti tramite HTTPS. Le richieste HTTP semplici vengono rifiutate.

Capacità Chiave

Capacità	Descrizione
Ricerca Alimentare	Ricerca a testo libero su oltre 3 milioni di voci alimentari con filtri per categoria, marca e paese
Ricerca Codice a Barre	Ottieni dati nutrizionali tramite UPC, EAN o altri formati di codice a barre
Dettagli Nutrizionali	Profilo nutrizionale completo per qualsiasi alimento (oltre 70 nutrienti, compresi i micronutrienti)
Dimensioni delle Porzioni	Dimensioni delle porzioni standard e alternative con conversioni in grammi
Analisi delle Ricette	Invia un elenco di ingredienti e ottieni dati nutrizionali combinati
Categorie Alimentari	Naviga nella tassonomia gerarchica delle categorie alimentari
Directory dei Brand	Cerca e naviga tra i produttori di alimenti di marca
Autocompletamento	Suggerimenti rapidi per la ricerca alimentare

Formato della Risposta

Tutte le risposte seguono una struttura coerente:

{
  "status": "success",
  "data": { },
  "meta": {
    "request_id": "req_abc123",
    "rate_limit_remaining": 245,
    "rate_limit_reset": "2026-03-10T15:00:00Z"
  }
}

Le risposte di errore includono un codice di errore leggibile dalla macchina e un messaggio comprensibile:

{
  "status": "error",
  "error": {
    "code": "FOOD_NOT_FOUND",
    "message": "Nessuna voce alimentare corrisponde all'ID fornito.",
    "request_id": "req_xyz789"
  }
}

Autenticazione

Tutte le richieste API richiedono una chiave API passata nell'intestazione Authorization.

Ottenere una Chiave API

1. Crea un account sviluppatore su developer.nutrola.com
2. Naviga alla sezione Chiavi API nel tuo dashboard
3. Genera una nuova chiave e specifica gli ambiti di cui hai bisogno
4. Conserva la chiave in modo sicuro — verrà visualizzata solo una volta

Utilizzare la Tua Chiave API

Includi la chiave in ogni intestazione della richiesta:

Authorization: Bearer YOUR_API_KEY

Esempio con curl:

curl -H "Authorization: Bearer ntr_live_abc123def456" \
  https://api.nutrola.com/v1/foods/search?q=chicken+breast

Ambiti della Chiave API

Ambito	Livello di Accesso
foods:read	Ricerca e recupero dati alimentari (il più comune)
barcodes:read	Ricerca codice a barre
recipes:analyze	Analisi nutrizionale delle ricette
brands:read	Accesso alla directory dei brand
categories:read	Tassonomia delle categorie alimentari

Le chiavi possono essere limitate a capacità specifiche. Una chiave con solo foods:read non può accedere alle ricerche di codice a barre. Questo segue il principio del minimo privilegio: richiedi solo gli ambiti di cui la tua applicazione ha bisogno.

Endpoint Principali

Ricerca Alimentare

Cerca nel database per nome, parola chiave o frase.

GET /v1/foods/search

Parametri:

Parametro	Tipo	Richiesto	Descrizione
q	string	Sì	Query di ricerca (es. "petto di pollo grigliato")
category	string	No	Filtra per categoria alimentare (es. "latticini", "verdure")
brand	string	No	Filtra per nome della marca
country	string	No	Codice paese ISO 3166-1 alpha-2 (es. "US", "DE", "JP")
verified_only	boolean	No	Restituisci solo voci con dati di origine verificati (default: true)
page	integer	No	Numero di pagina per la paginazione (default: 1)
per_page	integer	No	Risultati per pagina, max 50 (default: 20)

Esempio di Richiesta:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.nutrola.com/v1/foods/search?q=greek+yogurt&country=US&per_page=5"

Esempio di Risposta:

{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "food_8f2k9d",
        "name": "Yogurt Greco, Naturale, Magro",
        "brand": null,
        "category": "dairy",
        "country": "US",
        "verified": true,
        "source": "USDA",
        "nutrition_per_100g": {
          "calories": 59,
          "protein": 10.2,
          "carbohydrates": 3.6,
          "fat": 0.4,
          "fiber": 0,
          "sugar": 3.2,
          "sodium": 36
        },
        "default_serving": {
          "description": "1 contenitore (170g)",
          "grams": 170
        }
      }
    ],
    "total_results": 342,
    "page": 1,
    "per_page": 5
  }
}

Ottieni Dettagli Alimentari

Recupera il profilo nutrizionale completo per un alimento specifico.

GET /v1/foods/{food_id}

Esempio di Richiesta:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.nutrola.com/v1/foods/food_8f2k9d"

La risposta dettagliata include la suddivisione completa dei nutrienti — oltre 70 nutrienti, compresi tutte le vitamine, minerali, aminoacidi e profili di acidi grassi. Include anche tutte le dimensioni delle porzioni disponibili e le loro equivalenti in grammi.

Risposta Parziale (Nutrienti Chiave):

{
  "status": "success",
  "data": {
    "id": "food_8f2k9d",
    "name": "Yogurt Greco, Naturale, Magro",
    "nutrition_per_100g": {
      "calories": 59,
      "protein": 10.2,
      "carbohydrates": 3.6,
      "fat": 0.4,
      "fiber": 0,
      "sugar": 3.2,
      "saturated_fat": 0.1,
      "monounsaturated_fat": 0.1,
      "polyunsaturated_fat": 0,
      "cholesterol": 5,
      "sodium": 36,
      "potassium": 141,
      "calcium": 110,
      "iron": 0.1,
      "vitamin_a": 4,
      "vitamin_c": 0,
      "vitamin_d": 0
    },
    "serving_sizes": [
      { "description": "1 contenitore (170g)", "grams": 170 },
      { "description": "1 tazza (245g)", "grams": 245 },
      { "description": "1 cucchiaio (15g)", "grams": 15 },
      { "description": "100g", "grams": 100 }
    ],
    "allergens": ["latte"],
    "source": "USDA",
    "source_id": "170903",
    "last_verified": "2026-02-15",
    "confidence_score": 0.98
  }
}

Ricerca Codice a Barre

Cerca un prodotto alimentare tramite il suo codice a barre.

GET /v1/barcodes/{barcode}

Formati Supportati: UPC-A, UPC-E, EAN-13, EAN-8

Esempio di Richiesta:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.nutrola.com/v1/barcodes/0049000006346"

La risposta restituisce lo stesso oggetto di dettaglio alimentare dell'endpoint /foods/{food_id}, con campi specifici per il codice a barre come barcode_format e regional_variants (un array di ID alimentari per lo stesso prodotto in diversi paesi, che potrebbero avere formulazioni diverse).

Analisi delle Ricette

Invia un elenco di ingredienti e ricevi la suddivisione nutrizionale combinata.

POST /v1/recipes/analyze

Corpo della Richiesta:

{
  "name": "Overnight Oats",
  "servings": 2,
  "ingredients": [
    { "food_id": "food_3k8m2n", "grams": 160 },
    { "food_id": "food_9p4q7r", "grams": 400 },
    { "food_id": "food_1a5b8c", "grams": 60 },
    { "food_id": "food_6d2e9f", "grams": 2, "description": "pizzico di sale" }
  ]
}

Puoi anche inviare gli ingredienti come testo per l'analisi automatica:

{
  "name": "Overnight Oats",
  "servings": 2,
  "ingredients_text": "160g di avena, 400ml di latte intero, 60g di burro di arachidi, pizzico di sale"
}

Risposta:

{
  "status": "success",
  "data": {
    "name": "Overnight Oats",
    "servings": 2,
    "nutrition_per_serving": {
      "calories": 425,
      "protein": 18.5,
      "carbohydrates": 42.3,
      "fat": 21.2,
      "fiber": 5.8
    },
    "nutrition_total": {
      "calories": 850,
      "protein": 37.0,
      "carbohydrates": 84.6,
      "fat": 42.4,
      "fiber": 11.6
    },
    "ingredients_matched": [
      { "input": "160g di avena", "matched_food": "food_3k8m2n", "confidence": 0.97 },
      { "input": "400ml di latte intero", "matched_food": "food_9p4q7r", "confidence": 0.99 },
      { "input": "60g di burro di arachidi", "matched_food": "food_1a5b8c", "confidence": 0.96 },
      { "input": "pizzico di sale", "matched_food": "food_6d2e9f", "confidence": 0.88 }
    ]
  }
}

Autocompletamento

Suggerimenti rapidi per la ricerca per costruire interfacce di ricerca.

GET /v1/foods/autocomplete?q={query}

Parametri:

Parametro	Tipo	Richiesto	Descrizione
q	string	Sì	Query di ricerca parziale (minimo 2 caratteri)
limit	integer	No	Risultati massimi, 1-10 (default: 5)
country	string	No	Prioritizza i risultati da questo paese

I tempi di risposta sono ottimizzati per l'uso interattivo — tipicamente sotto i 50 ms. L'endpoint di autocompletamento restituisce oggetti alimentari semplificati (ID, nome, marca e categoria) per un rendering rapido.

Limiti di Richiesta e Prezzi

Piano Gratuito

Il piano gratuito è progettato per sviluppo, test e applicazioni di piccole dimensioni:

Limite	Valore
Richieste al giorno	500
Richieste al minuto	30
Risultati di ricerca alimentare per richiesta	20
Analisi delle ricette al giorno	10
Ricerche di codici a barre al giorno	100

Piano Crescita

Per applicazioni di produzione con traffico moderato:

Limite	Valore
Richieste al giorno	25.000
Richieste al minuto	300
Risultati di ricerca alimentare per richiesta	50
Analisi delle ricette al giorno	500
Ricerche di codici a barre al giorno	5.000
Prezzo	$49/mese

Piano Enterprise

Per applicazioni ad alto traffico, soluzioni white-label e requisiti personalizzati:

Caratteristica	Dettagli
Richieste al giorno	Personalizzate (tipicamente oltre 100K)
Limiti di richiesta	Personalizzati
Supporto dedicato	Incluso
SLA	Garanzia di uptime del 99.9%
Esportazioni di dati personalizzate	Disponibili
Notifiche webhook	Disponibili per aggiornamenti dei dati
Prezzo	Contatta le vendite

Le informazioni sui limiti di richiesta sono incluse in ogni risposta API tramite l'oggetto meta e negli header delle risposte HTTP (X-RateLimit-Remaining, X-RateLimit-Reset).

Casi d'Uso Reali

App per Fitness e Allenamento

Se stai costruendo un'app per il fitness e vuoi aggiungere il tracciamento nutrizionale senza dover costruire un database alimentare da zero, l'API di Nutrola è la via più veloce. Utilizza gli endpoint di ricerca alimentare e codice a barre per consentire agli utenti di registrare i pasti, e l'endpoint di analisi delle ricette per voci di pasti personalizzati.

Piattaforme di Pianificazione dei Pasti

Le app di pianificazione dei pasti necessitano di dati nutrizionali accurati per generare piani che raggiungano obiettivi specifici di macronutrienti. La suddivisione dettagliata dei nutrienti dell'API (oltre 70 nutrienti) consente un'ottimizzazione precisa del piano dei pasti, non solo calorie e macronutrienti, ma anche micronutrienti, allergeni e compatibilità con restrizioni dietetiche.

Sanità e Telemedicina

Le piattaforme sanitarie che monitorano la nutrizione dei pazienti possono integrarsi con l'API per fornire un tracciamento alimentare accurato all'interno delle loro interfacce esistenti. Le fonti di dati verificate (USDA, EFSA, direttamente dai produttori) soddisfano gli standard di accuratezza richiesti per il monitoraggio nutrizionale clinico.

Ristorazione e Servizi Alimentari

Le piattaforme di ordinazione dei ristoranti possono utilizzare l'API per visualizzare informazioni nutrizionali per gli articoli del menu. L'endpoint di analisi delle ricette è particolarmente utile qui: invia gli ingredienti di un piatto e ottieni la suddivisione nutrizionale completa senza dover calcolare manualmente ogni voce.

Ricerca e Accademia

I ricercatori nutrizionali possono utilizzare l'API per standardizzare la codifica degli alimenti negli studi dietetici. I dati coerenti e verificati riducono l'errore di misurazione che affligge gli studi che si basano su dati nutrizionali riportati dai partecipanti.

Esempi di Codice

Python: Cerca un Alimento e Ottieni Dettagli Nutrizionali

import requests

API_KEY = "ntr_live_your_key_here"
BASE_URL = "https://api.nutrola.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

# Cerca un alimento
search_response = requests.get(
    f"{BASE_URL}/foods/search",
    headers=headers,
    params={"q": "petto di pollo grigliato", "per_page": 3}
)

results = search_response.json()["data"]["results"]

for food in results:
    print(f"{food['name']} - {food['nutrition_per_100g']['calories']} cal/100g")

# Ottieni dettagli completi per il primo risultato
food_id = results[0]["id"]
detail_response = requests.get(
    f"{BASE_URL}/foods/{food_id}",
    headers=headers
)

food_detail = detail_response.json()["data"]
nutrition = food_detail["nutrition_per_100g"]

print(f"\n{food_detail['name']}")
print(f"Calorie: {nutrition['calories']}")
print(f"Proteine: {nutrition['protein']}g")
print(f"Carboidrati: {nutrition['carbohydrates']}g")
print(f"Grassi: {nutrition['fat']}g")
print(f"Dimensioni delle porzioni: {food_detail['serving_sizes']}")

JavaScript: Integrazione della Scansione del Codice a Barre

const API_KEY = "ntr_live_your_key_here";
const BASE_URL = "https://api.nutrola.com/v1";

async function lookupBarcode(barcode) {
  const response = await fetch(
    `${BASE_URL}/barcodes/${barcode}`,
    {
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    }
  );

  if (!response.ok) {
    if (response.status === 404) {
      console.log("Prodotto non trovato nel database");
      return null;
    }
    throw new Error(`Errore API: ${response.status}`);
  }

  const data = await response.json();
  return data.data;
}

// Esempio di utilizzo
const product = await lookupBarcode("0049000006346");

if (product) {
  const serving = product.default_serving;
  const factor = serving.grams / 100;

  console.log(`${product.name} (${product.brand})`);
  console.log(`Per ${serving.description}:`);
  console.log(`  Calorie: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
  console.log(`  Proteine: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
  console.log(`  Carboidrati: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
  console.log(`  Grassi: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}

Swift: Costruire un Campo di Ricerca Autocompletamento

import Foundation

class Nutrola API {
    private let apiKey: String
    private let baseURL = "https://api.nutrola.com/v1"

    init(apiKey: String) {
        self.apiKey = apiKey
    }

    func autocomplete(query: String, limit: Int = 5) async throws -> [FoodSuggestion] {
        guard query.count >= 2 else { return [] }

        var components = URLComponents(string: "\(baseURL)/foods/autocomplete")!
        components.queryItems = [
            URLQueryItem(name: "q", value: query),
            URLQueryItem(name: "limit", value: String(limit))
        ]

        var request = URLRequest(url: components.url!)
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")

        let (data, _) = try await URLSession.shared.data(for: request)
        let response = try JSONDecoder().decode(AutocompleteResponse.self, from: data)
        return response.data.suggestions
    }
}

struct FoodSuggestion: Codable {
    let id: String
    let name: String
    let brand: String?
    let category: String
}

struct AutocompleteResponse: Codable {
    let status: String
    let data: AutocompleteData
}

struct AutocompleteData: Codable {
    let suggestions: [FoodSuggestion]
}

Migliori Pratiche per la Gestione degli Errori

L'API utilizza codici di stato HTTP standard:

Codice di Stato	Significato	Causa Comune
200	Successo	Richiesta completata normalmente
400	Richiesta Non Valida	Parametro richiesto mancante o valore non valido
401	Non Autorizzato	Chiave API non valida o mancante
403	Vietato	La chiave API non ha l'ambito richiesto
404	Non Trovato	ID alimento o codice a barre non presente nel database
429	Limite di Richiesta Raggiunto	Troppe richieste; controlla gli header dei limiti di richiesta
500	Errore del Server	Errore interno; riprova con un backoff esponenziale

Quando ricevi una risposta 429, l'intestazione Retry-After ti indica quanti secondi aspettare prima di riprovare. È fortemente consigliato implementare un backoff esponenziale per le risposte 429 e 500 nelle applicazioni di produzione.

Freschezza e Aggiornamenti dei Dati

Il database di Nutrola viene aggiornato continuamente. Le voci di prodotti di marca vengono rinfrescate quando i produttori segnalano modifiche, tipicamente entro 48 ore. Le voci del database governativo vengono sincronizzate trimestralmente quando vengono pubblicate nuove versioni.

Se la tua applicazione memorizza nella cache le risposte API (cosa che raccomandiamo per le prestazioni), suggeriamo un TTL della cache di 24 ore per le risposte dettagliate sugli alimenti e 1 ora per i risultati di ricerca. Il campo last_verified nelle risposte dettagliate sugli alimenti ti indica quando la voce è stata confermata come accurata per l'ultima volta.

Per i clienti enterprise, offriamo notifiche webhook quando le voci alimentari vengono aggiornate, in modo che la tua applicazione possa invalidare i dati memorizzati nella cache in modo proattivo invece di aspettare la scadenza del TTL della cache.

Iniziare

1. Registrati su developer.nutrola.com — ci vogliono meno di un minuto
2. Genera una chiave API con gli ambiti di cui hai bisogno
3. Effettua la tua prima richiesta utilizzando gli esempi curl sopra
4. Esplora la documentazione interattiva su developer.nutrola.com/docs dove puoi testare gli endpoint direttamente nel tuo browser
5. Unisciti alla community degli sviluppatori sul nostro server Discord per supporto, richieste di funzionalità e per vedere cosa stanno costruendo altri sviluppatori

Se hai domande, incontri problemi o desideri discutere di un'integrazione enterprise, contatta il nostro team di relazioni con gli sviluppatori all'indirizzo api@nutrola.com.

FAQ

L'API Nutrola è gratuita da utilizzare?

Sì, esiste un piano gratuito che include 500 richieste al giorno. Questo è adatto per sviluppo, test e applicazioni di piccole dimensioni. Per applicazioni di produzione con traffico più elevato, il piano Crescita parte da $49 al mese con 25.000 richieste giornaliere. I piani Enterprise con limiti personalizzati sono disponibili per casi d'uso ad alto traffico.

Quali formati di dati supporta l'API?

L'API utilizza esclusivamente JSON sia per le richieste che per le risposte. Tutti gli endpoint accettano parametri di query standard per le richieste GET e corpi di richiesta JSON per le richieste POST. La codifica delle risposte è UTF-8, che gestisce correttamente i nomi degli alimenti in tutte le lingue supportate.

Quanto è accurato il dato nutrizionale fornito dall'API?

Ogni voce nel database di Nutrola passa attraverso un processo di verifica multilivello che include la validazione delle fonti governative, il confronto dei dati con i produttori, il controllo statistico alimentato dall'IA e la revisione da parte di esperti umani. Il nostro benchmark di accuratezza è del 97,4% rispetto all'analisi di laboratorio, rispetto a una media del settore del 70-85% per i database crowdsourced. Ogni voce alimentare include un campo confidence_score che indica il nostro livello di certezza.

Posso utilizzare l'API per costruire un prodotto commerciale?

Sì. L'API è progettata per l'uso commerciale. Il piano gratuito può essere utilizzato per prodotti commerciali entro i suoi limiti di richiesta. I piani Crescita e Enterprise includono diritti di utilizzo commerciale senza restrizioni sul tipo di applicazione. Consulta i termini di servizio su developer.nutrola.com per ulteriori dettagli.

L'API supporta alimenti provenienti da paesi al di fuori degli Stati Uniti?

Sì. Il database copre prodotti di marca provenienti da 47 paesi e alimenti generici da oltre 120 cucine. Utilizza il parametro country sugli endpoint di ricerca per dare priorità ai risultati di un mercato specifico. Le ricerche di codici a barre abbinano automaticamente il prodotto alla corretta formulazione regionale.

Come gestisco gli alimenti che non sono nel database?

Se una ricerca di codice a barre restituisce un 404, puoi tornare a una ricerca testuale utilizzando il nome del prodotto. Se nessun approccio trova l'alimento, puoi inviarlo per l'aggiunta tramite il portale per sviluppatori. Gli alimenti inviati dai partner API vengono prioritizzati per la verifica e tipicamente aggiunti entro 72 ore. I clienti enterprise possono richiedere aggiunte in blocco per grandi cataloghi di prodotti.

Sono disponibili SDK o librerie client?

Forniamo librerie client ufficiali per Python (via pip: pip install nutrola), JavaScript/TypeScript (via npm: npm install @nutrola/api) e Swift (via Swift Package Manager). Queste librerie gestiscono l'autenticazione, i limiti di richiesta, i retry e l'analisi delle risposte. Sono disponibili librerie mantenute dalla community per Go, Ruby e PHP.