API de base de données alimentaire

Ce que fait une requête

GET /v1/foods/{id} prend l'UUID obtenu par une recherche ou une recherche par code-barres et renvoie toute la fiche normalisée. Pas de sélection de champs ni de pagination : la fiche de 62ea12b8-b260-c288-5c38-3a4906f5d6dd (code-barres 5449000000996, source openfoodfacts) revient avec toutes les clés du schéma 200, et ce qui manque à la source vaut null au lieu d'être omis.

Authentifiez-vous avec l'en-tête X-API-Key. La seule entrée facultative est ?lang=, parmi en, fr, es, de, it ou bg. Elle ajoute category_localized, category_segments_localized et allergens_localized et ne touche à aucune autre clé : ajouter lang plus tard ne casse donc jamais un parseur existant. Chaque réponse porte aussi un en-tête X-Request-Id à citer dans vos demandes de support.

Noms, ingrédients et entrée principale

name et ingredients sont des tableaux de {lang, text}. La première entrée a lang main et reprend name_default et ingredients_default ; product_lang vous indique quelle langue réelle c'est. Sur la fiche Coca-Cola, le nom principal est Original Taste, l'entrée fr est Coca-Cola en canette et l'entrée bg est Кока-Кола. Choisissez l'entrée correspondant à la langue de votre interface et repliez-vous sur name_default.

Attendez-vous à ce que ingredients soit plus long que le nombre de langues : Open Food Facts stocke le texte des ingrédients par variante d'emballage, si bien qu'une même lang peut apparaître plusieurs fois sur une fiche, souvent avec un texte identique, comme ici. Dédoublonnez sur lang et gardez la première occurrence. Le texte est saisi par les contributeurs et renvoyé tel quel ; l'entrée ar contient ici des fragments d'étiquette qui ne sont pas des ingrédients : validez-le avant de le transformer en structures.

Catégorie, tags, allergènes et lang

category est une chaîne unique jointe par des virgules, du général au précis : Beverages and beverages preparations,Beverages,Carbonated drinks,Sodas,Colas,pt:bebidas cafeína. Découpez sur la virgule ; le dernier niveau est le plus précis. categories_tags contient les mêmes niveaux sous forme de tags machine (en:beverages, en:carbonated-drinks, en:colas) et c'est la valeur stable sur laquelle filtrer ou regrouper, car la chaîne d'affichage change quand des contributeurs modifient le produit.

allergens et traces utilisent les mêmes tags de style en:milk, tout comme countries (en:albania, en:austria, en:belgium) et labels. null signifie que la source n'a rien indiqué, pas que le produit est sans allergènes ; cette fiche a allergens: null et traces: null, donc un avertissement allergie doit afficher inconnu, pas aucun.

Avec ?lang=bg, l'API ajoute category_localized en une chaîne traduite, category_segments_localized avec une entrée par niveau de hiérarchie, et allergens_localized parallèle à allergens. Un niveau ou un tag sans entrée de dictionnaire vaut null dans le tableau : gardez l'index aligné sur categories_tags ou allergens et repliez-vous sur le tag anglais pour les cases null.

Scores, portion et nutriments résumés

nutriscore est une lettre minuscule (e ici), nova_group un nombre (4) et ecoscore_grade une chaîne qui peut être une lettre ou une valeur sentinelle comme not-applicable, ce que renvoie cette boisson. Traitez les trois comme pouvant être null et n'associez pas not-applicable à une couleur.

serving_size_raw et quantity sont du texte libre copié depuis l'étiquette. serving_size_raw indique 1 can (330 ml) et convient à l'affichage ; quantity indique 0kg sur cette fiche, une erreur de contributeur : ne calculez jamais le poids de l'emballage à partir de ce champ sans contrôle de cohérence.

nutrition_summary donne six valeurs pour 100 g : energy_kcal, proteins_g, carbs_g, fat_g, sugars_g et fiber_g. Chacune peut être null séparément et l'objet peut être null quand la source n'a pas de tableau nutritionnel. Il suffit pour une ligne de liste ou une comparaison rapide ; les 40+ nutriments complets sont sur l'API de nutrition à /v1/foods/{id}/nutrients avec le même id.

Id stables, cache et flux habituel

L'id est déterministe, dérivé de la source et de l'identifiant produit propre à la source : le même produit obtient le même UUID à chaque réimportation. Stockez les id dans vos propres tables et récupérez-les à nouveau des mois plus tard sans étape de remappage. barcode peut être null dans le schéma : préférez l'id au code-barres comme clé de jointure.

Un 200 porte Cache-Control: public, max-age=300 et un 404 max-age=60 : un CDN ou un cache HTTP devant votre service les respecte sans configuration. Si vous mettez en cache dans votre propre base, indexez sur id plus lang, car les clés localisées diffèrent selon la langue.

Le flux habituel : obtenez un id avec l'API de recherche alimentaire ou l'API de recherche par code-barres, stockez-le, et appelez cet endpoint quand une vue de détail a besoin de la fiche complète. Pour rafraîchir de nombreux id stockés à la fois, l'API de consultation groupée d'aliments accepte une liste en une requête à partir de Starter. Les images sont des photos de contributeurs Open Food Facts hébergées sur images.openfoodfacts.org et les fiches d'autres sources peuvent ne pas en avoir : affichez une image par défaut chaque fois que image_url vaut null.