Skip to content
Newtrition Data

Migration Guide (v1 -> v2)

High-level overview

Section titled “High-level overview”

Compared to v1, v2 introduces three main changes:

  1. Serving sizes are returned directly in food and search responses.
  2. Labels are included in multiple places (especially nutrient values and search variants).
  3. FoodDTO includes additional nutrient fields (see full list below).

Important for existing integrations:

  • /api/* without explicit version still points to v1 (legacy behavior).
  • v2 is available only under /api/v2/*.

1) Route: GET /api/v2/food/{id}

Section titled “1) Route: GET /api/v2/food/{id}”

Object: food_service.FoodDTO

What is new in v2 vs v1:

  • serving_sizes is included (v1 does not return this field).
  • serving_sizes[].type uses these values:
    • package
    • portion
    • pinch
    • tablespoon
    • teaspoon
    • small_whole
    • medium_whole
    • large_whole
    • small_piece
    • medium_piece
    • large_piece
    • small_slice
    • medium_slice
    • large_slice
    • small_bottle
    • medium_bottle
    • large_bottle
    • small_glass
    • medium_glass
    • large_glass
    • small_cup
    • medium_cup
    • large_cup
    • small_bowl
    • medium_bowl
    • large_bowl
    • small_toe
    • medium_toe
    • large_toe
  • Legacy v1 fields are no longer part of the v2 contract:
    • quantity_value
    • quantity_unit
  • Nutrients are represented as Quantity objects with labels:
    • Structure: { "label": string, "amount": number, "unit": string }

Additional nutrient fields in v2 (vs v1):

  • vaccenic_acid
  • gondoic_acid
  • rumenic_acid
  • gamma_linolenic_acid
  • dihomo_gamma_linolenic_acid
  • nitrogen
  • chromium
  • molybdenum
  • retinol_activity_equivalent
  • folate
  • folate_natural
  • ergocalciferol
  • cholecalciferol
  • beta_tocopherol
  • delta_tocopherol
  • gamma_tocopherol
  • alpha_tocotrienol
  • vitamin_K
  • menaquinone
  • acetic_acid
  • citric_acid
  • lactic_acid
  • malic_acid
  • tartaric_acid
  • oligosaccharides
  • fiber_high_molecular_weight
  • fiber_insoluble_high_molecular_weight
  • fiber_soluble_high_molecular_weight
  • fiber_low_molecular_weight
  • fatty_acids_other
  • carotenoids_ex_beta_carotene

2) Route: GET /api/v2/search

Section titled “2) Route: GET /api/v2/search”

Object: ApiFoodSearchResponse with data[] as SearchFoodData

What is new in v2 vs v1:

  • serving_sizes is included for each result.
  • serving_sizes[].type uses the same serving key set as above.
  • quantity_value / quantity_unit (v1 legacy fields) are not part of v2.
  • processed_variants[] now includes:
    • label (human-readable processing label)
  • processed_variants[].big7 quantities include labels:
    • e.g. energy.label, protein.label, etc.

3) Route: GET /api/v2/search/gtin

Section titled “3) Route: GET /api/v2/search/gtin”

Object: ApiGtinSearchResponse with data as SearchFoodData

What is new in v2 vs v1:

  • Same structural updates as GET /api/v2/search:
    • serving_sizes included
    • serving_sizes[].type uses the same serving key set as above
    • processed_variants[].label included
    • labels in processed_variants[].big7.*.label
    • no quantity_value / quantity_unit

4) Route: POST /api/v2/evaluate/nutrition-summary

Section titled “4) Route: POST /api/v2/evaluate/nutrition-summary”

Object: Nutrition Summary

What is new in v2 vs v1:

  • All quantity fields include labels (label, amount, unit).

5) Route: POST /api/v2/evaluate/macro-distribution

Section titled “5) Route: POST /api/v2/evaluate/macro-distribution”

Object: Macro Distribution

What is new in v2 vs v1:

  • breakdown[] now includes an additional label field per macro component.

6) Route: POST /api/v2/evaluate/healthy-eating-index

Section titled “6) Route: POST /api/v2/evaluate/healthy-eating-index”

Object: HEI Report

What is new in v2 vs v1:

  • components[] now includes an additional label field.
  • component is constrained to a fixed set of values (enum behavior).

Current component values:

  • total_fruits
  • whole_fruits
  • total_vegetables
  • greens_and_beans
  • whole_grains
  • dairy
  • total_protein_foods
  • seafood_and_plant_proteins
  • refined_grains
  • added_sugars
  • saturated_fats
  • fatty_acids
  • sodium

7) Route: POST /api/v2/evaluate/energy-density

Section titled “7) Route: POST /api/v2/evaluate/energy-density”

Object: Energy Density Report

What is new in v2 vs v1:

  • sum_energy_liquids now includes an additional label field.
  • energy_density[] now includes an additional label field per entry.

Integration notes

Section titled “Integration notes”
  • If you currently use quantity_value / quantity_unit from v1, migrate in v2 to:
    • serving_sizes[] for package/portion sizes,
    • Quantity objects (label, amount, unit) for nutrients.
  • Expect additional fields in v2 responses (especially nutrients).
  • If your deserialization is strict, update DTOs to handle additive fields.