Tailored Mealplan API

A method to fetch a set of meals supporting a certain nutrition goal

This API description is of Tailored Meal Plan API used internally by our B2C applications. While it effectively demonstrates the technology capability, it should not be used for any production implementations since we have to align the exact behavior and algorithm details behind it. After this alignment we will implement a separate endpoint with similar but not the same contract.

Some of our APIs including this are subject to move from camelCase to snake_case field naming convention.

The host provided below is for sandbox testing only. We will communicate the production hostname and path separately

Swagger spec

Get Tailored Mealplan

GET https://api-x.whisk.com/v1/health/recommend?

Path Parameters

Name

Type

Description

period.startDate.year*

number

Local date period start to return meal plan for. Inclusive

period.startDate.month*

number

Local date period start to return meal plan for. Inclusive

period.startDate.day*

number

Local date period start to return meal plan for. Inclusive

period.endDate.year*

number

Local date period end to return meal plan for. Inclusive. For non Samsung+ users max period is limited to 3 days

period.endDate.month*

number

Local date period end to return meal plan for. Inclusive. For non Samsung+ users max period is limited to 3 days

period.endDate.day*

number

Local date period end to return meal plan for. Inclusive. For non Samsung+ users max period is limited to 3 days

mealTimes*

array

Meal times which should be recommended. The options are:

MEAL_TIME_BREAKFAST MEAL_TIME_LUNCH MEAL_TIME_DINNER MEAL_TIME_SNACK

limit

number

Number of options to be recommended for each meal time. Defaults to 1

responseMask.paths

array

Extra fields to return on the meal. For performance reasons, we recommend including only requiredresponseMask.paths. Doing so will make the server respond faster by only returning the essential meal data. The full list of supported fields is available below.

country

string

ISO 3166-1 two letter country code. We may boost certain meals depending on user's country. The list of supported countries will be communicated separately

language

string

ISO 639-1 two letter language code. We return certain text fields localized. We do not perform mapping country to language. Client should select and pass language explicitly. The list of supported languages will be communicated separately

filters.calorieGoal

number

Daily calorie target to recommend meals towards to. If user did not pass health onboarding default is 2000cal. Using filters may limit the recommendation meal pool and return partial or empty result. The reasonable value is from 1800 to 3500 cal

filters.macroRatios.proteinRatio

number

Ratio of proteins in the recommendations in percentage. Default is 25% . Using filters may limit the recommendation meal pool and return partial or empty result. The reasonable value is from 20% to 40%

filters.macroRatios.fatRatio

number

Ratio of fats in the recommendations in percentage. Default is 25% . Using filters may limit the recommendation meal pool and return partial or empty result. The reasonable value is from 20% to 65%

filters.macroRatios.carbohydrateRatio

number

Ratio of carbs in the recommendations in percentage. Default is 50% . Using filters may limit the recommendation meal pool and return partial or empty result. The reasonable value is from 10% to 60%

Headers

Name

Type

Description

X-Whisk-App-Name

String

Integration name for smart response version control. I.e. different recommendation algorithms for different versions.

X-Whisk-App-Version

String

Integration version for smart response version control. I.e. different recommendation algorithms for different versions.

{
  "recommendation":[
    {
      "date":{
        "year":2023,
        "month":10,
        "day":16
      },
      "meal_time":"MEAL_TIME_LUNCH",
      "recommended_meals":[
        {
          "recommended_food":[
            {
              "recipe":{
                "recipe":{
                  "id":"107cecbf85bc87d43f88fc8d8760224cc20",
                  "name":"Banana Split Oatmeal"
                }
              }
            }
          ]
        }
      ]
    },
    {
      "date":{
        "year":2023,
        "month":10,
        "day":16
      },
      "meal_time":"MEAL_TIME_SNACK",
      "recommended_meals":[
        {
          "recommended_food":[
            {
              "recipe":{
                "recipe":{
                  "id":"10701895002830479fc863825d93e287b34",
                  "name":"Strawberry Banana Sour Cream Muffins"
                }
              }
            }
          ]
        }
      ]
    },
    {
      "date":{
        "year":2023,
        "month":10,
        "day":17
      },
      "meal_time":"MEAL_TIME_LUNCH",
      "recommended_meals":[
        {
          "recommended_food":[
            {
              "recipe":{
                "recipe":{
                  "id":"10160635c51d2e458fb4e86cc5db5068cc52ae93668",
                  "name":"Almond Butter, Strawberry & Banana Overnight Oats with Chia"
                }
              }
            }
          ]
        }
      ]
    },
    {
      "date":{
        "year":2023,
        "month":10,
        "day":17
      },
      "meal_time":"MEAL_TIME_SNACK",
      "recommended_meals":[
        {
          "recommended_food":[
            {
              "food":{
                "food":{
                  "id":"20271891b7fa95840298c139ac558320585",
                  "title":"Oat, cooked",
                  "attribute_id":"a8b495f5-6c73-47d9-9b2f-3bb0eb6c0916",
                  "measures_qty":{
                    "measure_qty":[
                      {
                        "simple":{
                          "amount":156,
                          "unit":{
                            "name":"G",
                            "display_name":"g"
                          }
                        },
                        "detailed":{
                          "quantity":1,
                          "measure":{
                            "name":"cup",
                            "amount":156,
                            "unit":{
                              "name":"G",
                              "displayName":"g"
                            }
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

{
	"code": "general.badRequest",
	"message": "period.startDate is incorrect"
}

{
    // Response
}

{
    // Response
}

You may take a look on the page powered by this API here.

List of supported `responseMask.paths`

More detailed description on each recipe-related field could be found there

recipe.name
recipe.description
recipe.ingredients
recipe.instructions
recipe.images
recipe.servings
recipe.durations
recipe.normalized_ingredients
recipe.normalized_ingredients.nutrition
recipe.nutrition
recipe.language
recipe.save_count
recipe.updated_at
recipe.labels
food.title
food.image_url
food.measures_qty
food.attribute_id

Sample Request

The example below requests one meal option for Breakfast and Lunch for 2 days. Recipe names and food titles are requested of all possible response payload.

For ApiKey access use Token instead of Bearer

curl -v -X GET "https://api-x.qa.whisk-dev.com/v1/health/recommend?period.startDate.year=2023&period.startDate.month=10&period.startDate.day=16&period.endDate.year=2023&period.endDate.month=10&period.endDate.day=17&mealTimes=MEAL_TIME_LUNCH&mealTimes=MEAL_TIME_SNACK&limit=1&responseMask.paths=food.title&responseMask.paths=recipe.name&filters.calorieGoal=2500&filters.macroRatios.proteinRatio=20&filters.macroRatios.fatRatio=20&filters.macroRatios.carbohydrateRatio=60" -H "accept: application/json" -H "Authorization: Bearer %TOKEN%" -H "X-Whisk-App-Name: sh" -H "X-Whisk-App-Version: 0.0.1"

Response

Data returned in JSON. Empty strings, zero values, empty arrays and null values are not returned.

Json response example with the proper response_mask.paths specified

{
  "recommendation":[
    {
      "date":{
        "year":2023,
        "month":10,
        "day":16
      },
      "meal_time":"MEAL_TIME_LUNCH",
      "recommended_meals":[
        {
          "recommended_food":[
            {
              "recipe":{
                "recipe":{
                  "id":"107cecbf85bc87d43f88fc8d8760224cc20",
                  "name":"Banana Split Oatmeal"
                }
              }
            }
          ]
        }
      ]
    },
    {
      "date":{
        "year":2023,
        "month":10,
        "day":16
      },
      "meal_time":"MEAL_TIME_SNACK",
      "recommended_meals":[
        {
          "recommended_food":[
            {
              "recipe":{
                "recipe":{
                  "id":"10701895002830479fc863825d93e287b34",
                  "name":"Strawberry Banana Sour Cream Muffins"
                }
              }
            }
          ]
        }
      ]
    },
    {
      "date":{
        "year":2023,
        "month":10,
        "day":17
      },
      "meal_time":"MEAL_TIME_LUNCH",
      "recommended_meals":[
        {
          "recommended_food":[
            {
              "recipe":{
                "recipe":{
                  "id":"10160635c51d2e458fb4e86cc5db5068cc52ae93668",
                  "name":"Almond Butter, Strawberry & Banana Overnight Oats with Chia"
                }
              }
            }
          ]
        }
      ]
    },
    {
      "date":{
        "year":2023,
        "month":10,
        "day":17
      },
      "meal_time":"MEAL_TIME_SNACK",
      "recommended_meals":[
        {
          "recommended_food":[
            {
              "food":{
                "food":{
                  "id":"20271891b7fa95840298c139ac558320585",
                  "title":"Oat, cooked",
                  "measures_qty":{
                    "measure_qty":[
                      {
                        "simple":{
                          "amount":156,
                          "unit":{
                            "name":"G",
                            "display_name":"g"
                          }
                        },
                        "detailed":{
                          "quantity":1,
                          "measure":{
                            "name":"cup",
                            "amount":156,
                            "unit":{
                              "name":"G",
                              "displayName":"g"
                            }
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Core attributes

Some terminology before continuing

Meal in recommended_meals refers to a set of Food consumed during a specific mealtime of the day. In our current understanding it’s the same as Course. If several courses are taken they are represented by different meal instances. A Food or Food Item Combo can make up a meal.

Food in recommended_food- a substance with known nutrition to be eaten. Recipe, Ontology product, Base Item, Dish can be instances of Food

Combo meal food item - a Meal featuring two or more single food items or recipes usually eaten in a single approach e.g. an Apple and a slice of bread with butter. A Grandma's oatmeal recipe and a banana.

Mealtime - a commonly accepted time frame for consuming food. We have 4 meal times, Lunch, Breakfast, Dinner, Snack. This pattern is adopted by FDA. Different cultures may have additional mealtimes (e.g. Afternoon tea, Brunch). We disregard them in sake of model simplicity now. Each mealtime may consist of several Meals (Courses)

Name

Type

Description

recommendation

array

top-level container object

recommendation.date

object

target date for recommended meal

recommendation.date.year

number

recommendation.date.month

number

recommendation.date.day

number

recommendation.meal_time

string

one of requested target mealtimes. MEAL_TIME_BREAKFAST MEAL_TIME_LUNCH MEAL_TIME_DINNER MEAL_TIME_SNACK

recommendation.recommended_meals

array

a list of different recommended meals according to the requested limit. For certain restricted dietary cases may have fewer meals than the limit

recommendation.recommended_meals.recommended_food

array

a list of food recommended within certain meal

recommendation.recommended_meals.recommended_food.recipe

object

Container object

recommendation.recommended_meals.recommended_food.recipe.recipe

object

recommendation.recommended_meals.recommended_food.food

object

Container object

recommendation.recommended_meals.recommended_food.food.food

object

Food object

recommendation.recommended_meals.recommended_food.food.food.title

string

Localized food title

recommendation.recommended_meals.recommended_food.food.food.image_url

string

Food image url on our CDN

recommendation.recommended_meals.recommended_food.food.food.measures_qty

object

Recommended food measurement

recommendation.recommended_meals.recommended_food.food.food.measures_qty.simple

object

Measure recommended in simple units e.g. grams, ounces, milliliters. Includes numeric Amount and localized unit name

recommendation.recommended_meals.recommended_food.food.food.measures_qty.detailed

object

Measure recommended in more human readable form.

recommendation.recommended_meals.recommended_food.food.food.measures_qty.detailed.quantity

number

number of measures recommended e.g. 3 [slice of cheese]

recommendation.recommended_meals.recommended_food.food.food.measures_qty.detailed.measure

object

Measure details

recommendation.recommended_meals.recommended_food.food.food.measures_qty.detailed.measure.name

string

Localized measure name e.g. slice

recommendation.recommended_meals.recommended_food.food.food.measures_qty.detailed.measure.amount

number

Number of simple units within the measure

recommendation.recommended_meals.recommended_food.food.food.measures_qty.detailed.measure.unit

object

Localized simple unit name e.g. gram, ounce

PreviousHealthy recipe only recommendations for DA NextRecipe recommendations for SH

Last updated 6 months ago

Swagger spec

Get Tailored Mealplan

Path Parameters

Headers

List of supported responseMask.paths

Sample Request

Response

Json response example with the proper response_mask.paths specified

Core attributes

List of supported `responseMask.paths`