API de nutrition

Une requête, cinq groupes, pour 100 g

GET /v1/foods/{id}/nutrients prend l'UUID de l'aliment dans le chemin et rien d'autre : ni paramètres de requête, ni corps, ni lang. L'id est le même que celui que renvoient tous les autres endpoints : un résultat de l'API de recherche alimentaire ou de l'API de recherche par code-barres devient un détail complet en un appel de plus. Les id sont déterministes d'une réimportation à l'autre : vous pouvez les stocker et continuer à appeler cette URL.

La réponse est un objet plat avec food_id plus cinq groupes fixes : macros, fats, minerals, vitamins et other. Chaque clé est toujours présente et chaque valeur est soit un nombre, soit null. Le schéma actuel compte 41 champs de nutriments, d'où le chiffre de 40+. Les unités figurent dans le nom de la clé (energy_kcal, sodium_mg, selenium_mcg, vitamin_a_iu) : pas besoin de table d'unités séparée.

Toutes les valeurs sont pour 100 g du produit tel que vendu. Pour afficher une portion, multipliez par les grammes divisés par 100. Le serving_size_raw de la fiche est un texte d'étiquette (pour la fiche Coca-Cola de l'exemple, "1 can (330 ml)"), donc la conversion de ce texte en grammes est à votre charge.

• macros (10 clés) couvre l'énergie en kcal et kJ, protéines, glucides, lipides, sucres, fibres, alcool, amidon et polyols ; fats (7) ajoute saturés, trans, mono- et polyinsaturés, omega3, omega6 et cholesterol_mg
• minerals (12) va de sodium_mg et salt_g à selenium_mcg et iodine_mcg ; vitamins (11) donne A et D en UI, B9 et B12 en mcg, le reste en mg ; other contient added_sugars_g

Bien lire les null et les zéros

La réponse d'exemple pour l'aliment 62ea12b8-b260-c288-5c38-3a4906f5d6dd montre le schéma typique d'Open Food Facts : energy_kcal 42, energy_kj 180.2, carbs_g 10.6, sugars_g 10.6, added_sugars_g 5.3, des zéros explicites pour proteins_g, fat_g, saturated_fat_g, sodium_mg et salt_g, et null pour tout le reste, de fiber_g à l'ensemble du groupe vitamins.

Traitez ces deux états différemment. Un 0 est une valeur déclarée par la source ; un null signifie que le nutriment ne figure ni sur l'étiquette ni dans la source. Ne convertissez jamais null en 0 avant d'additionner les apports d'une journée, sinon un repas composé de produits partiellement étiquetés sous-estimera silencieusement vitamines et minéraux. Affichez plutôt un tiret ou « non déclaré ».

La couverture dépend de la provenance. Les lignes de source usda_foundation ou usda_sr_legacy sont des analyses de laboratoire de l'USDA et remplissent les groupes vitamines et minéraux : la plupart des clés sont des nombres. Les lignes de source usda (USDA Branded Foods) et celles d'Open Food Facts sont transcrites depuis l'emballage : fiables pour les nutriments obligatoires de l'étiquette, souvent null au-delà. Le champ source de la fiche vous dit dans quel cas vous êtes avant d'afficher le tableau.

• Affichez null comme inconnu, pas comme zéro ; n'agrégez que les clés non null pour tous les éléments du repas.
• sodium_mg et salt_g existent tous deux car les étiquettes diffèrent selon les régions ; utilisez celui qu'attend votre public et repliez-vous sur l'autre.

Quand cet appel est vraiment nécessaire

Chaque fiche de l'API de base de données alimentaire et chaque résultat par code-barres inclut déjà nutrition_summary avec six valeurs principales : energy_kcal, proteins_g, carbs_g, fat_g, sugars_g et fiber_g. Les résultats de recherche sont des lignes allégées qui ne l'ont pas. Pour un résultat de scan, une carte de détail ou un enregistrement rapide de calories, cet objet suffit généralement et ne consomme aucun détail nutritionnel.

Réservez /nutrients à l'écran de détail ou au moment où l'utilisateur s'intéresse au sodium, aux acides gras saturés, au cholestérol ou à une vitamine précise. Cherchez ou scannez, affichez le résumé, récupérez le détail au toucher. Sur le forfait Free, c'est aussi ce qui vous maintient dans la limite de 25 par jour pendant le développement.

Les en-têtes de réponse capturés ne contiennent pas de Cache-Control : le cache est donc à votre charge. Les id sont stables et les valeurs ne changent que lors d'une réimportation du produit : un cache indexé sur food_id et conservé des heures ou des jours est sûr.

La limite du forfait Free, en-tête par en-tête

Sur le forfait Free, chaque détail réussi décompte un compteur quotidien séparé de 25, indiqué dans chaque réponse par X-RateLimit-Nutrients-Limit, X-RateLimit-Nutrients-Remaining et X-RateLimit-Nutrients-Reset. Lisez Remaining avant une série de récupérations de détails et vous pourrez vous replier sur nutrition_summary au lieu de buter sur la limite en pleine session.

À zéro, l'endpoint renvoie un 429 avec l'erreur "Nutrients daily allowance exceeded", une upgrade_url dans le corps, et Retry-After contenant les secondes restantes jusqu'à minuit UTC. Un appel refusé ne consomme ni détail ni requête quotidienne, et ne décale pas la réinitialisation. Les forfaits payants n'ont pas ce compteur ; leurs appels de nutriments ne sont limités que par le quota quotidien de requêtes du forfait (partagé entre toutes les clés du compte) et la limite par seconde de chaque clé.

Si vous êtes sur Starter ou plus et traitez un gros catalogue, récupérez d'abord les fiches de base via l'API de consultation groupée d'aliments et n'appelez /nutrients que pour les id dont le résumé ne suffit pas.