API de recherche par code-barres

Ce que fait une recherche

Envoyez GET /v1/foods/barcode/{code} avec votre clé dans l'en-tête X-API-Key. Le code va du GTIN-8 au GTIN-14, 20 caractères au maximum. FoodBase essaie d'abord une correspondance exacte avec le code-barres stocké, puis les équivalents avec zéros de remplissage du même nombre : un UPC-A à 12 chiffres trouve ainsi la fiche stockée sous forme d'EAN à 13 chiffres.

Pour 5449000000996, la fiche revient avec barcode 5449000000996 et id 62ea12b8-b260-c288-5c38-3a4906f5d6dd. Cet id est stable d'une réimportation à l'autre : stockez-le comme clé étrangère plutôt que la chaîne du code-barres.

Quand plusieurs lignes du catalogue portent le même code-barres, la plus populaire l'emporte et le choix est déterministe : le même code renvoie le même produit à chaque appel.

• Le barcode renvoyé est la forme stockée, pas forcément celle que vous avez envoyée.

Lire la fiche

Le corps du 200 est la même fiche alimentaire complète que celle que renvoie l'API de base de données alimentaire par id : analysez-la une fois et réutilisez le parseur. Pour 5449000000996, cela donne source openfoodfacts, name_default Original Taste avec des entrées bg et fr dans le tableau name, nutriscore e, nova_group 4 et ecoscore_grade not-applicable. Les textes d'étiquette comme serving_size_raw (1 can (330 ml)) et quantity (0kg sur cette fiche, une erreur de contributeur) sont renvoyés tels que saisis depuis l'emballage : traitez-les comme une indication, pas comme un nombre.

• categories_tags est la taxonomie lisible par machine (en:colas) ; category est le même chemin sous forme de chaîne d'affichage jointe par des virgules.
• allergens et traces valent null quand la source n'en mentionne aucun, ce qui ne veut pas dire sans allergènes.
• image_url pointe vers images.openfoodfacts.org et peut changer quand des contributeurs mettent le produit à jour.

Localisation et nutrition

Ajoutez ?lang=bg (ou en, fr, es, de, it) pour remplir category_localized, category_segments_localized et allergens_localized à partir des dictionnaires de traduction. Quand aucune traduction n'existe, le champ vaut null plutôt qu'un repli en anglais : gardez donc category et allergens dans votre chaîne de repli. lang ne touche ni name ni ingredients.

nutrition_summary a six clés : energy_kcal, proteins_g, carbs_g, fat_g, sugars_g, fiber_g. Chacune peut être null, et l'objet entier vaut null quand la source n'a enregistré aucune donnée nutritionnelle. Pour le tableau complet pour 100 g, plus de 40 nutriments quand la source les fournit, appelez l'API de nutrition avec l'id que vous venez de recevoir.

Flux de scan, cache et échecs

En cas de 200, affichez la carte à partir de name_default, brand, image_url et nutrition_summary, et gardez l'id. En cas de 404, le code n'est pas dans le catalogue : basculez vers l'API de reconnaissance d'images alimentaires avec une photo de la face avant, ou proposez une recherche textuelle. Ne réessayez pas un 404 ; il ne changera pas tant que le catalogue n'est pas mis à jour.

Les réponses 200 portent Cache-Control: public, max-age=300, et les 404 peuvent être mis en cache 60 secondes. Respectez-les dans tout cache placé entre vos utilisateurs et FoodBase. Chaque réponse porte aussi X-RateLimit-Second-Remaining et les en-têtes de quota quotidien ; régulez votre débit grâce à eux avant de recevoir un 429.

La couverture est meilleure pour les produits de grande distribution européens et américains, car le catalogue est construit à partir d'Open Food Facts et d'USDA FoodData Central, complétés par GS1 Bulgaria et Metro Bulgaria. Les marques de distributeur et les produits très récents sont les absences les plus fréquentes.