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.

200

{
  "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"
                            }
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

400 If some request parameter is invalid, unsupported, or out of bound

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

403: Forbidden

{
    // Response
}

500: Internal Server Error

{
    // 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	Detailed recipe object description
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