Zum Inhalt springen
Newtrition Data

Migrationsleitfaden (v1 -> v2)

Kurzüberblick

Abschnitt betitelt „Kurzüberblick“

Mit v2 erhalten Sie im Vergleich zu v1 vor allem drei fachliche Erweiterungen:

  1. Serving Sizes werden in Food- und Search-Antworten direkt ausgegeben.
  2. Labels werden an mehreren Stellen mitgeliefert (insbesondere bei Nährwerten und Search-Varianten).
  3. FoodDTO enthält zusätzliche Nährwerte (neue Felder, siehe unten).

Wichtig für bestehende Integrationen:

  • /api/* ohne Versionspfad zeigt weiterhin auf v1 (Legacy-Verhalten).
  • v2 ist nur unter /api/v2/* erreichbar.

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

Abschnitt betitelt „1) Route: GET /api/v2/food/{id}“

Objekt: food_service.FoodDTO

Neu in v2 gegenüber v1:

  • serving_sizes ist enthalten (v1 gibt dieses Feld nicht zurück).
  • serving_sizes[].type nutzt diese Werte:
    • 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-Felder aus v1 sind nicht mehr Teil des v2-Vertrags:
    • quantity_value
    • quantity_unit
  • Nährwerte sind als Quantity mit Label aufgebaut:
    • Struktur: { "label": string, "amount": number, "unit": string }

Neue Nährwert-Felder in v2 (gegenüber 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

Abschnitt betitelt „2) Route: GET /api/v2/search“

Objekt: ApiFoodSearchResponse mit data[] als SearchFoodData

Neu in v2 gegenüber v1:

  • Pro Treffer ist serving_sizes enthalten.
  • serving_sizes[].type verwendet denselben Serving-Key-Satz wie oben.
  • quantity_value / quantity_unit (v1-Legacy) sind nicht Teil von v2.
  • processed_variants[] enthält ein zusätzliches Feld:
    • label (menschenlesbare Bezeichnung der Verarbeitung)
  • In processed_variants[].big7 enthalten die Mengen Labels:
    • z. B. energy.label, protein.label, etc.

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

Abschnitt betitelt „3) Route: GET /api/v2/search/gtin“

Objekt: ApiGtinSearchResponse mit data als SearchFoodData

Neu in v2 gegenüber v1:

  • Entspricht denselben Struktur-Updates wie bei GET /api/v2/search:
    • serving_sizes enthalten
    • serving_sizes[].type verwendet denselben Serving-Key-Satz wie oben
    • processed_variants[].label enthalten
    • Labels in processed_variants[].big7.*.label
    • kein quantity_value / quantity_unit

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

Abschnitt betitelt „4) Route: POST /api/v2/evaluate/nutrition-summary“

Objekt: Nutrition Summary

Neu in v2 gegenüber v1:

  • Alle Quantity-Felder enthalten Labels (label, amount, unit).

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

Abschnitt betitelt „5) Route: POST /api/v2/evaluate/macro-distribution“

Objekt: Macro Distribution

Neu in v2 gegenüber v1:

  • breakdown[] enthält jetzt ein zusätzliches Feld label je Makro-Komponente.

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

Abschnitt betitelt „6) Route: POST /api/v2/evaluate/healthy-eating-index“

Objekt: HEI Report

Neu in v2 gegenüber v1:

  • components[] enthält jetzt ein zusätzliches Feld label.
  • component ist in v2 auf einen festen Satz von Werten ausgelegt (Enum-Verhalten).

Aktuelle component-Werte:

  • 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

Abschnitt betitelt „7) Route: POST /api/v2/evaluate/energy-density“

Objekt: Energy Density Report

Neu in v2 gegenüber v1:

  • sum_energy_liquids enthält ein zusätzliches Feld label.
  • energy_density[] enthält ein zusätzliches Feld label pro Eintrag.

Technische Hinweise für Integrationen

Abschnitt betitelt „Technische Hinweise für Integrationen“
  • Wenn Sie aktuell quantity_value / quantity_unit aus v1 verwenden, migrieren Sie für v2 auf:
    • serving_sizes[] für Portions-/Packungsgrößen,
    • Quantity-Objekte (label, amount, unit) für Nährwerte.
  • Rechnen Sie in v2 mit zusätzlichen Feldern (insbesondere bei Nährwerten).
  • Falls Ihre Deserialisierung strikt ist: DTOs bitte auf additive Felder vorbereiten.