L'API de données nutritionnelles Nutrola : comment les développeurs peuvent accéder à notre base de données alimentaire

Vous développez une application liée à la santé, au fitness ou à l'alimentation ? L'un des problèmes les plus difficiles que vous rencontrerez concerne les données nutritionnelles. Vous avez besoin d'informations précises sur les calories et les macronutriments pour des milliers d'aliments, ces données doivent couvrir des produits internationaux, et elles doivent rester à jour à mesure que les fabricants reformulent leurs produits.

La plupart des développeurs commencent par extraire des données de bases gouvernementales ouvertes comme USDA FoodData Central. Cela fournit une base, mais ne couvre pas les produits de marque de 47 pays, les repas de restaurant, ni les milliers d'aliments régionaux que les vrais utilisateurs consomment chaque jour. Combler ces lacunes par vous-même représente des années de travail de curation de données.

L'API de données nutritionnelles de Nutrola donne aux développeurs accès à la même base de données alimentaire vérifiée qui alimente notre application — plus de 3 millions d'entrées, couvrant les ingrédients bruts, les produits de marque, les repas de restaurant et les recettes composées. Chaque entrée est vérifiée grâce à notre processus de contrôle qualité multicouche, le même système auquel font confiance plus de 2 millions d'utilisateurs.

Ce guide couvre tout ce que vous devez savoir pour commencer à construire avec notre API : architecture, authentification, endpoints, limites de débit et exemples de code concrets.

Aperçu de l'API

L'API de données nutritionnelles Nutrola est une API JSON RESTful. Vous faites des requêtes HTTP, vous recevez des réponses JSON. Aucun SDK requis, bien que nous fournissions des bibliothèques clientes pour Python, JavaScript et Swift par commodité.

URL de base

https://api.nutrola.com/v1

Tous les endpoints sont servis via HTTPS. Les requêtes HTTP simples sont rejetées.

Fonctionnalités principales

Fonctionnalité	Description
Recherche d'aliments	Recherche en texte intégral parmi plus de 3M d'entrées alimentaires avec filtrage par catégorie, marque et pays
Recherche par code-barres	Obtenir les données nutritionnelles par UPC, EAN ou autres formats de codes-barres
Détails nutritionnels	Profil nutritionnel complet pour tout aliment (plus de 70 nutriments dont les micronutriments)
Tailles de portions	Portions standard et alternatives avec conversions en grammes
Analyse de recettes	Soumettre une liste d'ingrédients et obtenir les données nutritionnelles combinées
Catégories d'aliments	Parcourir la taxonomie hiérarchique des catégories alimentaires
Répertoire des marques	Rechercher et parcourir les fabricants d'aliments de marque
Auto-complétion	Suggestions rapides de saisie semi-automatique pour les interfaces de recherche alimentaire

Format de réponse

Toutes les réponses suivent une structure cohérente :

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

Les réponses d'erreur incluent un code d'erreur lisible par machine et un message lisible par l'humain :

{
  "status": "error",
  "error": {
    "code": "FOOD_NOT_FOUND",
    "message": "No food entry matches the provided ID.",
    "request_id": "req_xyz789"
  }
}

Authentification

Toutes les requêtes API nécessitent une clé API transmise dans l'en-tête Authorization.

Obtenir une clé API

1. Créez un compte développeur sur developer.nutrola.com
2. Accédez à la section Clés API dans votre tableau de bord
3. Générez une nouvelle clé et spécifiez les portées dont vous avez besoin
4. Stockez la clé de manière sécurisée — elle ne sera affichée qu'une seule fois

Utiliser votre clé API

Incluez la clé dans chaque en-tête de requête :

Authorization: Bearer YOUR_API_KEY

Exemple avec curl :

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

Portées des clés API

Portée	Niveau d'accès
foods:read	Rechercher et récupérer des données alimentaires (le plus courant)
barcodes:read	Recherche par code-barres
recipes:analyze	Analyse nutritionnelle de recettes
brands:read	Accès au répertoire des marques
categories:read	Taxonomie des catégories alimentaires

Les clés peuvent être limitées à des fonctionnalités spécifiques. Une clé avec uniquement foods:read ne peut pas accéder aux recherches par code-barres. Cela suit le principe du moindre privilège — ne demandez que les portées dont votre application a besoin.

Endpoints principaux

Recherche d'aliments

Recherchez dans la base de données par nom, mot-clé ou expression.

GET /v1/foods/search

Paramètres :

Paramètre	Type	Requis	Description
q	string	Oui	Requête de recherche (ex. : "grilled chicken breast")
category	string	Non	Filtrer par catégorie d'aliment (ex. : "dairy", "vegetables")
brand	string	Non	Filtrer par nom de marque
country	string	Non	Code pays ISO 3166-1 alpha-2 (ex. : "US", "DE", "JP")
verified_only	boolean	Non	Retourner uniquement les entrées avec des données source vérifiées (par défaut : true)
page	integer	Non	Numéro de page pour la pagination (par défaut : 1)
per_page	integer	Non	Résultats par page, max 50 (par défaut : 20)

Exemple de requête :

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

Exemple de réponse :

{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "food_8f2k9d",
        "name": "Greek Yogurt, Plain, Nonfat",
        "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 container (170g)",
          "grams": 170
        }
      }
    ],
    "total_results": 342,
    "page": 1,
    "per_page": 5
  }
}

Obtenir les détails d'un aliment

Récupérez le profil nutritionnel complet d'un aliment spécifique.

GET /v1/foods/{food_id}

Exemple de requête :

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

La réponse détaillée inclut le bilan nutritionnel complet — plus de 70 nutriments incluant toutes les vitamines, minéraux, acides aminés et profils d'acides gras. Elle inclut également toutes les tailles de portions disponibles et leurs équivalents en grammes.

Réponse partielle (nutriments clés) :

{
  "status": "success",
  "data": {
    "id": "food_8f2k9d",
    "name": "Greek Yogurt, Plain, Nonfat",
    "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 container (170g)", "grams": 170 },
      { "description": "1 cup (245g)", "grams": 245 },
      { "description": "1 tbsp (15g)", "grams": 15 },
      { "description": "100g", "grams": 100 }
    ],
    "allergens": ["milk"],
    "source": "USDA",
    "source_id": "170903",
    "last_verified": "2026-02-15",
    "confidence_score": 0.98
  }
}

Recherche par code-barres

Recherchez un produit alimentaire par son code-barres.

GET /v1/barcodes/{barcode}

Formats pris en charge : UPC-A, UPC-E, EAN-13, EAN-8

Exemple de requête :

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

La réponse retourne le même objet de détail alimentaire que l'endpoint /foods/{food_id}, avec des champs supplémentaires spécifiques au code-barres comme barcode_format et regional_variants (un tableau d'identifiants alimentaires pour le même produit dans différents pays, qui peuvent avoir des formulations différentes).

Analyse de recettes

Soumettez une liste d'ingrédients et recevez le bilan nutritionnel combiné.

POST /v1/recipes/analyze

Corps de la requête :

{
  "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": "pinch of salt" }
  ]
}

Vous pouvez également soumettre les ingrédients sous forme de texte pour un parsing automatique :

{
  "name": "Overnight Oats",
  "servings": 2,
  "ingredients_text": "160g rolled oats, 400ml whole milk, 60g peanut butter, pinch of salt"
}

Réponse :

{
  "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 rolled oats", "matched_food": "food_3k8m2n", "confidence": 0.97 },
      { "input": "400ml whole milk", "matched_food": "food_9p4q7r", "confidence": 0.99 },
      { "input": "60g peanut butter", "matched_food": "food_1a5b8c", "confidence": 0.96 },
      { "input": "pinch of salt", "matched_food": "food_6d2e9f", "confidence": 0.88 }
    ]
  }
}

Auto-complétion

Suggestions rapides de saisie semi-automatique pour créer des interfaces de recherche.

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

Paramètres :

Paramètre	Type	Requis	Description
q	string	Oui	Requête de recherche partielle (minimum 2 caractères)
limit	integer	Non	Nombre max de résultats, 1-10 (par défaut : 5)
country	string	Non	Prioriser les résultats de ce pays

Les temps de réponse sont optimisés pour une utilisation interactive — généralement moins de 50 ms. L'endpoint d'auto-complétion retourne des objets alimentaires simplifiés (ID, nom, marque et catégorie uniquement) pour un rendu rapide.

Limites de débit et tarification

Offre gratuite

L'offre gratuite est conçue pour le développement, les tests et les applications à petite échelle :

Limite	Valeur
Requêtes par jour	500
Requêtes par minute	30
Résultats de recherche alimentaire par requête	20
Analyses de recettes par jour	10
Recherches par code-barres par jour	100

Offre Croissance

Pour les applications en production avec un trafic modéré :

Limite	Valeur
Requêtes par jour	25 000
Requêtes par minute	300
Résultats de recherche alimentaire par requête	50
Analyses de recettes par jour	500
Recherches par code-barres par jour	5 000
Prix	49 $/mois

Offre Entreprise

Pour les applications à fort trafic, les solutions en marque blanche et les exigences personnalisées :

Fonctionnalité	Détails
Requêtes par jour	Personnalisé (généralement 100K+)
Limites de débit	Personnalisées
Support dédié	Inclus
SLA	Garantie de disponibilité 99,9 %
Exports de données personnalisés	Disponibles
Notifications webhook	Disponibles pour les mises à jour de données
Prix	Contacter le service commercial

Les informations de limite de débit sont incluses dans chaque réponse API via l'objet meta et dans les en-têtes de réponse HTTP (X-RateLimit-Remaining, X-RateLimit-Reset).

Cas d'utilisation concrets

Applications de fitness et d'entraînement

Si vous développez une application de fitness et souhaitez ajouter le suivi nutritionnel sans construire une base de données alimentaire de zéro, l'API de Nutrola est le chemin le plus rapide. Utilisez les endpoints de recherche alimentaire et de code-barres pour permettre aux utilisateurs d'enregistrer leurs repas, et l'endpoint d'analyse de recettes pour les entrées de repas personnalisés.

Plateformes de planification de repas

Les applications de planification de repas nécessitent des données nutritionnelles précises pour générer des plans qui atteignent des objectifs macro spécifiques. Le bilan nutritionnel détaillé de l'API (plus de 70 nutriments) permet une optimisation précise des plans de repas, pas seulement les calories et les macros, mais aussi les micronutriments, les allergènes et la compatibilité avec les restrictions alimentaires.

Santé et télémédecine

Les plateformes de santé qui surveillent la nutrition des patients peuvent s'intégrer à l'API pour fournir un enregistrement alimentaire précis au sein de leurs interfaces existantes. Les sources de données vérifiées (USDA, EFSA, données directes des fabricants) répondent aux normes de précision requises pour le suivi nutritionnel clinique.

Restauration et services alimentaires

Les plateformes de commande en restauration peuvent utiliser l'API pour afficher les informations nutritionnelles des plats du menu. L'endpoint d'analyse de recettes est particulièrement utile ici — soumettez les ingrédients d'un plat et obtenez le bilan nutritionnel complet sans calculer manuellement chaque élément.

Recherche et monde académique

Les chercheurs en nutrition peuvent utiliser l'API pour standardiser le codage alimentaire dans les études diététiques. Les données cohérentes et vérifiées réduisent l'erreur de mesure qui affecte les études reposant sur des données nutritionnelles déclarées par les participants.

Exemples de code

Python : rechercher un aliment et obtenir les détails nutritionnels

import requests

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

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

# Rechercher un aliment
search_response = requests.get(
    f"{BASE_URL}/foods/search",
    headers=headers,
    params={"q": "chicken breast grilled", "per_page": 3}
)

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

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

# Obtenir les détails complets pour le premier résultat
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"Calories: {nutrition['calories']}")
print(f"Protein: {nutrition['protein']}g")
print(f"Carbs: {nutrition['carbohydrates']}g")
print(f"Fat: {nutrition['fat']}g")
print(f"Serving sizes: {food_detail['serving_sizes']}")

JavaScript : intégration du scan de codes-barres

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("Product not found in database");
      return null;
    }
    throw new Error(`API error: ${response.status}`);
  }

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

// Exemple d'utilisation
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(`  Calories: ${Math.round(product.nutrition_per_100g.calories * factor)}`);
  console.log(`  Protein: ${(product.nutrition_per_100g.protein * factor).toFixed(1)}g`);
  console.log(`  Carbs: ${(product.nutrition_per_100g.carbohydrates * factor).toFixed(1)}g`);
  console.log(`  Fat: ${(product.nutrition_per_100g.fat * factor).toFixed(1)}g`);
}

Swift : créer un champ de recherche avec auto-complétion

import Foundation

class NutrolaAPI {
    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]
}

Bonnes pratiques de gestion des erreurs

L'API utilise les codes de statut HTTP standards :

Code de statut	Signification	Cause courante
200	Succès	La requête s'est terminée normalement
400	Requête incorrecte	Paramètre requis manquant ou valeur invalide
401	Non autorisé	Clé API invalide ou manquante
403	Interdit	La clé API n'a pas la portée requise
404	Non trouvé	L'identifiant alimentaire ou le code-barres n'est pas dans la base de données
429	Limite de débit atteinte	Trop de requêtes ; vérifiez les en-têtes de limite de débit
500	Erreur serveur	Erreur interne ; réessayez avec un backoff exponentiel

Lorsque vous recevez une réponse 429, l'en-tête Retry-After vous indique combien de secondes attendre avant de réessayer. L'implémentation d'un backoff exponentiel pour les réponses 429 et 500 est fortement recommandée pour les applications en production.

Fraîcheur des données et mises à jour

La base de données de Nutrola est mise à jour en continu. Les entrées de produits de marque sont actualisées lorsque les fabricants signalent des changements, généralement dans les 48 heures. Les entrées des bases de données gouvernementales sont synchronisées trimestriellement lors de la publication de nouvelles versions.

Si votre application met en cache les réponses de l'API (ce que nous recommandons pour la performance), nous suggérons un TTL de cache de 24 heures pour les réponses de détail alimentaire et de 1 heure pour les résultats de recherche. Le champ last_verified dans les réponses de détail alimentaire vous indique quand l'entrée a été confirmée comme exacte pour la dernière fois.

Pour les clients entreprise, nous offrons des notifications webhook lorsque les entrées alimentaires sont mises à jour, afin que votre application puisse invalider les données en cache de manière proactive plutôt que d'attendre l'expiration du TTL de cache.

Pour commencer

1. Inscrivez-vous sur developer.nutrola.com — cela prend moins d'une minute
2. Générez une clé API avec les portées dont vous avez besoin
3. Faites votre première requête en utilisant les exemples curl ci-dessus
4. Explorez la documentation interactive sur developer.nutrola.com/docs où vous pouvez tester les endpoints directement dans votre navigateur
5. Rejoignez la communauté des développeurs sur notre serveur Discord pour obtenir du support, faire des demandes de fonctionnalités et voir ce que les autres développeurs construisent

Si vous avez des questions, rencontrez des problèmes ou souhaitez discuter d'une intégration entreprise, contactez notre équipe de relations développeurs à api@nutrola.com.

FAQ

L'API Nutrola est-elle gratuite ?

Oui, il existe une offre gratuite qui comprend 500 requêtes par jour. Elle convient au développement, aux tests et aux applications à petite échelle. Pour les applications en production avec un trafic plus important, l'offre Croissance commence à 49 $ par mois avec 25 000 requêtes quotidiennes. Des plans Entreprise avec des limites personnalisées sont disponibles pour les cas d'utilisation à fort trafic.

Quels formats de données l'API prend-elle en charge ?

L'API utilise exclusivement le JSON pour les requêtes et les réponses. Tous les endpoints acceptent les paramètres de requête standards pour les requêtes GET et les corps de requête JSON pour les requêtes POST. L'encodage des réponses est UTF-8, ce qui gère correctement les noms d'aliments dans toutes les langues prises en charge.

Quelle est la précision des données nutritionnelles fournies par l'API ?

Chaque entrée de la base de données Nutrola passe par un processus de vérification multicouche comprenant la validation des sources gouvernementales, le croisement des données fabricants, une vérification statistique assistée par IA et une revue par des experts humains. Notre benchmark de précision est de 97,4 % par rapport à l'analyse en laboratoire, contre une moyenne du secteur de 70 à 85 % pour les bases de données participatives. Chaque entrée alimentaire inclut un champ confidence_score indiquant notre niveau de certitude.

Puis-je utiliser l'API pour créer un produit commercial ?

Oui. L'API est conçue pour un usage commercial. L'offre gratuite peut être utilisée pour des produits commerciaux dans le cadre de ses limites de débit. Les plans Croissance et Entreprise incluent des droits d'utilisation commerciale sans restriction sur le type d'application. Consultez les conditions d'utilisation sur developer.nutrola.com pour les détails complets.

L'API prend-elle en charge les aliments en dehors des États-Unis ?

Oui. La base de données couvre les produits de marque de 47 pays et les aliments génériques de plus de 120 cuisines. Utilisez le paramètre country sur les endpoints de recherche pour prioriser les résultats d'un marché spécifique. Les recherches par code-barres associent automatiquement le produit à la formulation régionale correcte.

Comment gérer les aliments qui ne sont pas dans la base de données ?

Si une recherche par code-barres retourne un 404, vous pouvez vous rabattre sur une recherche textuelle en utilisant le nom du produit. Si aucune des deux approches ne trouve l'aliment, vous pouvez le soumettre pour ajout via le portail développeur. Les aliments soumis par les partenaires API sont prioritaires pour la vérification et sont généralement ajoutés dans les 72 heures. Les clients entreprise peuvent demander des ajouts par lot pour les catalogues de produits volumineux.

Existe-t-il des SDK ou des bibliothèques clientes disponibles ?

Nous fournissons des bibliothèques clientes officielles pour Python (via pip : pip install nutrola), JavaScript/TypeScript (via npm : npm install @nutrola/api), et Swift (via Swift Package Manager). Ces bibliothèques gèrent l'authentification, les limites de débit, les tentatives de relance et le parsing des réponses. Des bibliothèques maintenues par la communauté sont disponibles pour Go, Ruby et PHP.