Migration Guide (v2 -> v2.1)

Migration guide: v2 to v2.1

High-level overview

Compared to v2, v2.1 introduces two main changes:

1. Three new standard attributes are added to food/search response objects:

   • standard_processing
   • standard_serving_type
   • standard_unit

2. Generic food source data has been updated from BLS version 3.0 to BLS 4.0, which may affect generic food availability, names, and IDs.

Important for existing integrations:

• The new fields are additive, but strict DTO/deserialization logic should be updated.
• Existing tracked/evaluated foods remain supported through an internal legacy mapping for at least 6 months after the cutoff.

---

1) Route: GET /api/v2.1/food/{id} and GET /api/v2.1/search?query=xyz

Object: food_service.FoodDTO

What is new in v2.1 vs v2

The responses now includes three additional standard attributes:

• standard_processing
• standard_serving_type
• standard_unit

---

standard_processing

standard_processing describes the processing state in which the food is most commonly consumed.

Examples:

• Noodles may have standard_processing: "cooked".
• Fresh fruit may have standard_processing: "raw".

This field is intended to improve nutrient accuracy. For example, 100 g raw noodles and 100 g cooked noodles can have very different nutrient profiles, while most users usually consume noodles cooked.

Important behavior:

• standard_processing is never empty.
• The default value is "raw".
• If a standard_processing value is provided, the corresponding processing variant for that food is guaranteed to exist.
• Possible values and more information can be found here:

Recommended integration behavior:

• Use standard_processing as the default processing state when presenting a food to users.
• This is especially important for foods commonly eaten cooked, prepared, dried, drained, or otherwise processed.

---

standard_serving_type

standard_serving_type indicates the serving size type that is most likely to be selected by users.

This can be used to preselect a serving size and reduce user interaction.

Important behavior:

• standard_serving_type can be null or empty.
• serving_sizes can also be empty, although this is rare.
• A food may have serving_sizes but no standard_serving_type.
• It is not possible for standard_serving_type to reference a serving type that does not exist in serving_sizes.
• Possible serving size keys are documented here:

Recommended integration behavior:

• If standard_serving_type is present, preselect the matching entry from serving_sizes.
• If standard_serving_type is missing, fall back to your existing serving-size selection behavior.
• If no suitable serving size exists, allow users to enter weight or volume manually.

---

standard_unit

standard_unit describes the unit users are typically expected to use for the food.

Allowed values:

• "g"
• "ml"

Important behavior:

• standard_unit is never empty.
• The default value is "g".
• This field reflects normal user-facing usage, not the nutritional science classification.

This is different from is_solid.

Example:

• Tomato soup may have:
  • standard_unit: "ml" because users usually measure it as a liquid
  • is_solid: true because it is treated as solid for nutritional energy-density calculations

Recommended integration behavior:

• Use standard_unit as the default unit for manual quantity input.
• Use "ml" for products normally measured as liquids.
• Use "g" for products normally measured by weight.
• Do not use is_solid to decide whether users should enter grams or milliliters.

---

2) Generic food source data update: BLS 4.0

v2.1 updates the generic food source data to BLS version 4.0.

This may result in changes to generic foods, including:

• Deleted generic foods
• Renamed generic foods
• Newly created generic foods
• Updated mappings between old and new generic food entries

Backward compatibility

To protect existing integrations and user histories, Newtrition Data provides an internal legacy mapping.

Important behavior:

• Users may no longer be able to search for old or deleted generic foods.
• Existing tracked foods remain evaluable through an internal mapping.
• Legacy generic foods are guaranteed to remain supported for evaluation for at least 6 months after the cutoff.

Example:

If a user tracked a generic food before the BLS 4.0 cutoff and that food was later deleted or renamed, the user may no longer find it through search. However, evaluations using the previously tracked food can still be processed via the internal legacy mapping.

Recommended integration behavior:

• Do not assume all previously searchable generic foods remain searchable.
• Keep stored food identifiers for already tracked foods.
• Continue sending stored food references for evaluation.
• Avoid replacing previously tracked generic foods solely based on search availability.
• Consider refreshing or remapping old generic foods in your own system before the compatibility period ends.

More information regarding legacy food data can be found here

---

Integration notes

DTO updates

Update DTOs for both food and search responses to include:

{
  "standard_processing": "raw",
  "standard_serving_type": "medium_piece",
  "standard_unit": "g"
}

Example with nullable serving type:

{
  "standard_processing": "raw",
  "standard_serving_type": null,
  "standard_unit": "g"
}

Recommended default selection logic

For food amount input, the recommended priority is:

1. Use standard_processing as the default processing state.
2. If standard_serving_type is present, preselect the matching serving_sizes[] entry.
3. Use standard_unit as the default manual input unit.
4. If no serving size is available, manual input in standard_unit should be shown.

Summary of changes from v2 to v2.1

Area	Change	Required action
Food response	Added standard_processing	Use as default processing state
Food response	Added standard_serving_type	Optionally preselect matching serving size
Food response	Added standard_unit	Use as default user-facing input unit
Search response	Added same three fields to each result	Update search DTOs and UI defaults
Generic foods	Source updated to BLS 4.0	Expect renamed, deleted, and new generic foods
Legacy foods	Internal mapping available	Existing tracked foods remain evaluable for at least 6 months