API de catégories d'aliments

Ce que renvoie une requête

GET /v1/categories lit une table précalculée de toutes les chaînes de catégorie distinctes du catalogue avec le nombre de produits qui les portent ; les produits sans catégorie sont exclus. Les lignes sont triées par product_count décroissant sans tri secondaire : ne comptez pas sur l'ordre des lignes à nombre égal.

q est un filtre de sous-chaîne insensible à la casse, pas un préfixe : q=chocolate trouve aussi bien "Chocolate", "en:chocolates" que "Beverages, Dairies, Dairy drinks, Flavoured milks, Chocolate milks", ce qui réduit la réponse capturée à un total de 11303 chaînes distinctes. Les espaces en bord sont supprimés, % et _ sont pris littéralement, et q est limité à 200 caractères.

limit va de 1 à 100 (20 par défaut) et offset de 0 à 10000 : avec limit=100 vous atteignez au plus les 10 100 premières lignes ; affinez avec q plutôt que de paginer plus loin. Les réponses portent Cache-Control: public, max-age=600, le serveur met en cache pendant une heure, et la table n'est reconstruite que lors d'une réimportation complète : récupérez-la une fois au démarrage ou pendant le build et stockez le résultat.

Deux formes de chaîne de catégorie

Les produits Open Food Facts portent une hiérarchie jointe par des virgules, du général au précis : "Snacks, Sweet snacks, Cocoa and its products, Chocolates, Dark chocolates". Les segments peuvent être des tags de taxonomie bruts avec un préfixe de langue à deux lettres ("en:chocolate-candies"), être dans la langue de l'étiquette ("Botanas, Snacks dulces, Cacao y sus productos, Chocolates, Chocolates negros"), et se terminent souvent par un fourre-tout comme en:groceries qui n'est pas le niveau le plus précis.

Les produits USDA portent une seule catégorie de distribution à plat, dont le nom peut lui-même contenir des virgules ("Chips, Pretzels & Snacks") ; ne la découpez jamais. Les lignes ici ne portent pas de source : si vous en avez besoin, récupérez un produit de la catégorie avec l'API de base de données alimentaire et lisez source à côté de category et categories_tags.

Une même hiérarchie peut apparaître sur plusieurs lignes : la réponse capturée liste séparément "Snacks, Sweet snacks, Cocoa and its products, Chocolates, Dark chocolates" (497 produits) et le même chemin sans espaces après les virgules (339). Fusionnez sur les segments nettoyés, pas sur la chaîne brute.

Construire un arbre de navigation ou une interface de filtres

Appliquez le nettoyage qu'utilise le site : découpez sur les virgules, supprimez les espaces, retirez un tag xx: en tête, remplacez les tirets par des espaces, mettez la première lettre en majuscule et supprimez les segments répétés sans tenir compte de la casse. Le premier segment nettoyé est la racine ; le dernier qui n'est pas un fourre-tout (groceries, food, foods, products, unknown, none) est la feuille. Le nombre d'un nœud est la somme des product_count de toutes les chaînes brutes qui y mènent.

• Nœuds racines : regroupez par premier segment nettoyé ("Snacks", "Beverages", "Botanas").
• Puces de feuille : le dernier segment qui n'est pas un fourre-tout ("Dark chocolates", "Chocolate milks").
• Noms USDA à plat : la chaîne entière est à la fois racine et feuille.
• Langue : les hiérarchies dans des langues différentes restent des nœuds séparés ; pour les traductions par produit, passez lang= à l'API de recherche alimentaire et lisez category_localized et category_segments_localized.
• L'arbre de navigation du site sur /categories/ applique les mêmes règles de nettoyage à ces données (et ne garde que les plus grandes feuilles) : servez-vous-en pour vérifier votre résultat.

D'une catégorie à ses produits

La recherche n'a pas de paramètre de catégorie. L'API de recherche alimentaire compare d'abord les noms de produits et les marques, et seulement si cela ne trouve rien, compare les mots de votre requête aux chaînes de catégorie. Envoyez comme q un segment nettoyé complet qui n'est pas lui-même un nom de produit, comme "Seeds & Related Snacks", et vous obtenez les produits de cette catégorie triés par popularité.

Le repli fonctionne par mots : "Seeds & Related Snacks" correspond donc à toute chaîne de catégorie contenant ces mots, dans n'importe quelle langue, et un segment qui est aussi un mot de produit courant ("Chocolate" ou "Dark chocolates") ne l'atteint jamais, car les noms de produits correspondent en premier. Pour une liste stricte, filtrez chaque résultat sur son champ category, qui est la chaîne brute renvoyée par cet endpoint.