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
Get Tailored Mealplan
GET
https://api-x.whisk.com/v1/health/recommend?
Path Parameters
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
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.
You may take a look on the page powered by this API here.
List of supported responseMask.paths
responseMask.paths
More detailed description on each recipe-related field could be found there
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
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
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)
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
Last updated