Diet & Health Labels

NutrientAPI automatically classifies every analyzed recipe with two types of labels: diet labels based on macronutrient ratios and health labels based on ingredient composition. Labels are applied deterministically by a rules engine after nutrient calculation -- no AI is involved in the labeling step.

Labels are included on all plans, including the free tier. There are no restrictions on which labels you receive.

Response Structure

Labels appear as arrays of strings in the API response:

{
  "diet_labels": ["high-protein", "low-carb"],
  "health_labels": ["gluten-free", "dairy-free"]
}

Both arrays can be empty if no labels apply. A recipe can have multiple diet labels and multiple health labels simultaneously.

Diet Labels

Diet labels describe the macronutrient profile of the recipe. They are calculated from the per-serving caloric contribution of each macronutrient. The formula converts grams to calories using standard Atwater factors (protein: 4 kcal/g, carbohydrate: 4 kcal/g, fat: 9 kcal/g), then expresses each as a percentage of total calories.

Label Criteria Description
high-protein Protein ≥ 25% of calories The recipe derives at least a quarter of its energy from protein. Typical for dishes centered on meat, fish, eggs, legumes, or dairy.
low-carb Carbs ≤ 20% of calories No more than a fifth of the recipe's energy comes from carbohydrates. Typical for dishes built around protein and fat without significant starch, sugar, or grain.
low-fat Fat ≤ 15% of calories Fat contributes no more than 15% of total energy. Typical for dishes based on lean protein, grains, fruits, and vegetables without added oils or fatty ingredients.
balanced Protein 15–25% of calories
Carbs 40–60% of calories		 The recipe falls within commonly recommended macronutrient ranges. Both the protein and carbohydrate thresholds must be met simultaneously.

How Diet Label Percentages Are Calculated

Here is an example for a recipe with 30g protein, 45g carbs, and 15g fat per serving:

// Step 1: Convert grams to calories
Protein calories  = 30g × 4 kcal/g = 120 kcal
Carb calories     = 45g × 4 kcal/g = 180 kcal
Fat calories      = 15g × 9 kcal/g = 135 kcal
Total calories    = 435 kcal

// Step 2: Calculate percentages
Protein %  = 120 / 435 = 27.6%  // ≥ 25% → high-protein
Carb %     = 180 / 435 = 41.4%  // 40-60% range → passes balanced carb check
Fat %      = 135 / 435 = 31.0%  // > 15% → NOT low-fat

// Step 3: Assign labels
diet_labels: ["high-protein"]
// "balanced" not assigned because protein > 25% exceeds the 15-25% range
Diet labels are not mutually exclusive with one exception. A recipe can be both high-protein and low-carb (common for grilled meat dishes). However, high-protein and balanced cannot co-occur since balanced requires protein between 15-25% while high-protein requires 25% or more.

Common Label Combinations

Recipe Type Typical Labels
Grilled chicken breast with vegetables high-protein, low-carb
Pasta with tomato sauce low-fat, balanced
Steak with butter and asparagus high-protein, low-carb
Rice and beans with salad balanced
Oatmeal with banana low-fat
Bacon and cheese omelette high-protein, low-carb

Health Labels

Health labels describe the dietary suitability of a recipe based on its ingredient composition. Unlike diet labels, which are calculated from nutrient ratios, health labels are determined by analyzing the matched USDA food categories for each ingredient.

Label Criteria Description
vegan No animal-derived ingredients The recipe contains no meat, poultry, fish, shellfish, dairy, eggs, honey, or other animal-derived ingredients. If any ingredient matches a USDA food category associated with animal products, this label is not applied.
vegetarian No meat, poultry, or fish The recipe contains no flesh from any animal. Dairy, eggs, and honey are permitted. All vegan recipes also qualify as vegetarian.
gluten-free No gluten-containing ingredients The recipe contains no wheat, barley, rye, triticale, or ingredients derived from these grains. Oats are excluded unless specifically labeled gluten-free in the input, since conventional oats are frequently cross-contaminated.
dairy-free No dairy ingredients The recipe contains no milk, cheese, butter, cream, yogurt, whey, casein, or other dairy-derived ingredients. This label is useful for lactose intolerance and milk allergy considerations.

Label Relationships

Health labels follow logical entailment rules:

  • Every vegan recipe is also vegetarian and dairy-free
  • A vegetarian recipe is not necessarily dairy-free (e.g., cheese pizza)
  • gluten-free is independent of the other health labels

Example Health Label Assignments

Recipe Health Labels
Black bean tacos with corn tortillas, avocado, salsa vegan, vegetarian, gluten-free, dairy-free
Caprese salad (tomato, fresh mozzarella, basil) vegetarian, gluten-free
Grilled salmon with lemon and dill gluten-free, dairy-free
Chicken parmesan with spaghetti (none)
Stir-fried tofu with rice and vegetables vegan, vegetarian, dairy-free

Using Labels in Your Application

Labels are returned as simple string arrays, making them easy to use for filtering, searching, or displaying dietary badges:

// Filter recipes suitable for a vegan user
const isVegan = data.health_labels.includes("vegan");

// Check if recipe meets multiple dietary criteria
const requiredLabels = ["gluten-free", "dairy-free"];
const meetsAll = requiredLabels.every(
  label => data.health_labels.includes(label)
);
Labels are informational, not medical advice. While the labeling rules engine is thorough, ingredient parsing works from natural language descriptions. Users with severe allergies should not rely solely on API-generated labels for safety decisions. Cross-contamination risks and trace ingredients are not captured.

Label Accuracy

Label accuracy depends directly on ingredient matching accuracy. If the API correctly identifies all ingredients in a recipe, the labels will be correct -- they are applied by a deterministic rules engine, not by AI. The accuracy bottleneck is always the parsing and matching step, not the labeling logic itself.

In practice, health label accuracy is very high for recipes with clearly stated ingredients. Ambiguous ingredients (e.g., "broth" without specifying chicken or vegetable) may cause occasional misclassification, which is reflected in the confidence scores returned with each ingredient.