openapi: 3.0.3
info:
title: Meal Planning API
description: |-
The *Meal Planning API* provides dietary planning based on a user-supplied daily meal structure and nutritional
constraints.
A meal plan is the assignment of a number of dishes, according to a fixed daily pattern, over a given period of
time. The daily pattern structures one or more *slots* (dishes) into a hierarchy of *sections*. An example meal
plan daily pattern might be:
1. Breakfast *(1 dish)*
2. Lunch *(section)*
1. Starter *(1 dish)*
2. Main course *(1 dish)*
3. Dessert *(1 dish)*
3. Dinner *(section)*
1. Main course *(1 dish)*
2. Dessert *(1 dish)*
The daily pattern is defined by the caller and is supplied to the meal planner with each `select` call.
Any section within the pattern may include acceptance criteria and nutritional constraints; a section's selection
criteria apply *separately* to each slot in that section's sub-tree; a section's nutritional constraints apply to
the *total* combined nutritional value of assigned slots in the section's sub-tree.
### Selection
A `select` call will attempt to generate a meal plan for a specified period from a given specification (daily
pattern plus criteria and constraints.) Upon successful generation, the meal plan will contain unique assignments
of recipes for each slot in the requested period.
Selection usually generates the same results from the same inputs (though this is not guaranteed.) To force
varying the output, include all recipes assigned so far as exclusions at the top-level section of the plan.
### Recipe details
The details of the assigned recipes can be retrieved through the *Recipe Search API* in one or more
[search-by-URI](https://developer.edamam.com/edamam-docs-recipe-api#operations-tag-Lookup_recipes_by_URI) calls
(search-by-URI access is always provided by meal planner subscriptions.) See the
[Recipe Search API](https://developer.edamam.com/edamam-docs-recipe-api) documentation for further details.
### Shopping list
Once a meal plan has been generated, a shopping list can be created for the requisite quantities of all necessary
ingredients across the plan, through the "Shopping List API".
See the [Recipe Search API](https://developer.edamam.com/edamam-docs-recipe-api) documentation for further details.
### Daily values
The daily values calculator call provides recommended daily allowance and upper intake limit values from a given
metabolic profile.
version: 1.2 beta
servers:
- url: https://api.edamam.com
tags:
- name: planner
description: Meal planning
- name: values
description: Daily values
paths:
/api/meal-planner/v1/{app_id}/select:
post:
tags:
- planner
summary: Create Dietary Plan According to Supplied Specification
parameters:
- name: app_id
in: path
required: true
schema:
type: string
- name: Edamam-Account-User
in: header
schema:
type: string
description: ID of the account user. Should be used *only* if the account is configured for active user tracking.
- name: beta
in: query
schema:
type: boolean
description: Turn on support for beta features
- name: type
in: query
required: true
explode: true
schema:
type: array
uniqueItems: true
items:
type: string
enum: [ public, edamam-generic ]
description: Types of recipes to choose from.
requestBody:
description: Meal plan descriptor
content:
application/json:
schema:
properties:
size:
description: Plan length (days)
type: integer
default: 1
minimum: 1
maximum: 14
plan:
$ref: '#/components/schemas/Section'
selection:
description: |
(BETA only) Plan assignment template, with explicit entries potentially assigned at specific slots.
The length of the generated plan, if successful, will equal the size of the template. Free slots
will be assigned to complete each day's value according to the constraints in effect. Pre-assigned
entries' nutritional value will be accounted for in nutritional constraint checking across the
daily assignment, but the individual pre-assigned entries will *not* be checked against applicable
acceptance criteria.
Items must be pre-assigned in accordance with the plan structure, as expected to be returned in a
successful plan assignment. Only leaf sections can be pre-assigned, assignments on non-leaf
sections will be reported back as invocation errors.
Assigned entries must exist. Non-existent entries will be reported with HTTP status 404.
This property is mutually exclusive with `size`; a call supplying both plan size and an assignment
template will be deemed invalid.
type: array
items:
$ref: '#/components/schemas/Selection'
examples:
7-Day Plan with Allergens:
$ref: '#/components/examples/7-Day-Plan-with-Allergens'
Vegan plan:
$ref: '#/components/examples/Vegan-plan'
responses:
200:
description: Plan generated completely or partially
content:
application/json:
schema:
properties:
status:
description: |
| Status | Description |
|---------------|-------------|
| `OK` | Plan generated completely |
| `INCOMPLETE` | Plan generated partially. Unique assignments for one or more days of the requested period could not be completed from available recipe data |
| `TIME_OUT` | Plan generated partially. Unique assignments for one or more days of the requested period could not be completed within the allowed execution time |
type: string
enum: [ OK, INCOMPLETE, TIME_OUT ]
_links:
description: Links to resources related to the generated meal plan
type: object
properties:
next:
allOf:
- description: >
(BETA only) Link for extending the current meal plan with one more complete period, with new
recipe entries. The link is only provided for convenience; it will *not* be available for
incomplete assignments (i.e. where `status` = `"INCOMPLETE"`,) or if the included extension
token has grown too large. It is highly recommended that the caller maintain their own chain
of extension requests, by keeping track of recipe entries assigned so far in the chain, and
adding them for exclusion on subsequent calls (see `exclude` in
[`Section`](#/components/schemas/Section).)
- $ref: '#/components/schemas/LinkEntry'
selection:
description: >
Daily assignments according to the specified plan. Each element of the array represents
complete assignments for a single day, each daily assignment corresponding with the structure of
the meals specified in the plan descriptor.
type: array
items:
$ref: '#/components/schemas/Selection'
examples:
Vegan plan assignment:
$ref: '#/components/examples/Vegan-plan-assignment'
400:
description: Malformed or invalid plan specification
404:
description: One or more pre-assigned entries were not found
security:
- basic:
- app_id
/api/daily-values/v1/values:
post:
tags:
- values
summary: Calculate Recommended Daily Intake and Tolerable Upper Limits for the Specified Metabolic Profile
requestBody:
description: Metabolic profile descriptor (possibly incomplete)
content:
application/json:
schema:
$ref: '#/components/schemas/MetabolicProfile'
examples:
Male, generic:
$ref: '#/components/examples/profile_Male_generic'
Male, complete:
$ref: '#/components/examples/profile_Male_complete'
Female, pregnant:
$ref: '#/components/examples/profile_Female_pregnant'
Female, complete:
$ref: '#/components/examples/profile_Female_complete'
responses:
200:
description: Daily values calculated
content:
application/json:
schema:
properties:
values:
description: Daily values, indexed by nutrient; nutrients are represented by **NutrientTag**-s
type: object
additionalProperties:
$ref: '#/components/schemas/Values'
examples:
Male, generic:
$ref: '#/components/examples/values_Male_generic'
Female, pregnant:
$ref: '#/components/examples/values_Female_pregnant'
400:
description: Malformed or inconsistent metabolic profile specification
security:
- basic:
- app_id
/api/recipes/v2/by-uri:
get:
tags:
- planner
summary: Lookup Recipes by URI
description: The meal planner returns recipe URIs as part of its response. Use this endpoint to retrieve the
recipes. For more information see the relevant documentation in the
[Recipe Search API](https://developer.edamam.com/edamam-docs-recipe-api#operations-tag-Lookup_recipes_by_URI).
responses:
default:
description: See the relevant documentation in the
[Recipe Search API](https://developer.edamam.com/edamam-docs-recipe-api#operations-tag-Lookup_recipes_by_URI).
/api/shopping-list/v2:
post:
tags:
- planner
summary: Create Shopping List From Total Meal Quantities
description: Once a meal plan has been generated, a shopping list can be created for the requisite quantities of
all necessary ingredients across the plan, through the "Shopping List API". For more information see the
relevant documentation in the [Recipe Search API](https://developer.edamam.com/edamam-docs-recipe-api).
responses:
default:
description: See the relevant documentation in the
[Recipe Search API](https://developer.edamam.com/edamam-docs-recipe-api).
components:
schemas:
Section:
description: |-
Plan section; may contain sub-sections.
Leaf sections (i.e. those that do not contain sub-sections) represent individual dishes in the daily plan.
Upon generation of the plan, complete or partial, each leaf section will be assigned a single recipe that will
be unique throughout the complete period of the generated plan.
type: object
properties:
accept:
allOf:
- description: Acceptance criteria for all entries in the sub-tree
- $ref: '#/components/schemas/Predicate'
fit:
description: >
Nutritional budget (constraints for total nutrient content values in the sub-tree.)
Keys must be valid **NutrientTag**-s
type: object
additionalProperties:
$ref: '#/components/schemas/Range'
exclude:
description: Recipes to exclude from this section's sub-tree, listed by URI
type: array
items:
type: string
sections:
description: |-
Sub-sections.
This section's acceptance criteria and nutritional budget will apply to its complete sub-tree of
sub-sections, potentially in conjunction will any other criteria that may apply, specifically from
containing parent sections.
type: object
additionalProperties:
$ref: '#/components/schemas/Section'
Selection:
type: object
properties:
assigned:
description: URI of the recipe assigned for this section (leaf sections only.)
type: string
_links:
description: Links to resources related to the assigned recipe
type: object
properties:
self:
allOf:
- description: Link to the assigned recipe's details in the Recipe Search API
- $ref: '#/components/schemas/LinkEntry'
sections:
description: Selection tree for sub-sections, according to the structure specified by the plan descriptor.
type: object
additionalProperties:
$ref: '#/components/schemas/Selection'
LinkEntry:
type: object
required: [href]
properties:
title:
description: Human-readable link title
type: string
href:
description: Target URL
type: string
Range:
type: object
properties:
min:
type: number
max:
type: number
Predicate:
oneOf:
- description: Select entries matching all of a given list of predicates
type: object
required: [all]
properties:
all:
type: array
items:
$ref: '#/components/schemas/Predicate'
- description: Select entries matching at least one out of a given list of predicates
type: object
required: [any]
properties:
any:
type: array
items:
$ref: '#/components/schemas/Predicate'
- description: Select entries that do *not* match a given predicate
type: object
required: [not]
properties:
not:
$ref: '#/components/schemas/Predicate'
- description: >
Select entries that satisfy a given target requirement, subject to a pre-condition. Entries that do *not*
satisfy the precondition will match this rule vacuously.
type: object
required: [when]
properties:
when:
type: object
required: [condition, require]
properties:
condition:
allOf:
- description: Pre-condition for checking the target requirement
- $ref: '#/components/schemas/Predicate'
require:
allOf:
- description: Target requirement to check if the pre-condition is satisfied
- $ref: '#/components/schemas/Predicate'
- description: Select entries falling under one or more of the supplied health labels
type: object
required: [health]
properties:
health:
type: array
items:
$ref: '#/components/schemas/HealthLabel'
- description: Select entries falling under one or more of the supplied caution labels
type: object
required: [caution]
properties:
caution:
type: array
items:
$ref: '#/components/schemas/CautionLabel'
- description: Select entries falling under one or more of the supplied cuisine types
type: object
required: [cuisine]
properties:
cuisine:
type: array
items:
$ref: '#/components/schemas/CuisineType'
- description: Select entries falling under one or more of the supplied meal types
type: object
required: [meal]
properties:
meal:
type: array
items:
$ref: '#/components/schemas/MealType'
- description: Select entries falling under one or more of the supplied dish types
type: object
required: [dish]
properties:
dish:
type: array
items:
$ref: '#/components/schemas/DishType'
- description: Select entries falling under one or more of the supplied dish types *only* (exclude entries under any other dish types)
type: object
required: [only-dish]
properties:
only-dish:
type: array
items:
$ref: '#/components/schemas/DishType'
- description: Select entries from one of the listed sources
type: object
required: [source]
properties:
source:
type: array
items:
type: string
- description: Select entries from one of the listed sources (by site name)
type: object
required: [source-name]
properties:
source-name:
type: array
items:
type: string
- description: Select entries with their number of ingredients in the specified range
type: object
required: [ingredients]
properties:
ingredients:
$ref: '#/components/schemas/Range'
- description: Select entries with their total preparation time in the specified range
type: object
required: [total-time]
properties:
total-time:
$ref: '#/components/schemas/Range'
HealthLabel:
type: string
enum: [ fat-free, low-fat-abs, sugar-conscious, low-sugar, low-potassium, kidney-friendly, keto-friendly,
plant-based, vegan, vegetarian, pescatarian, paleo, specific-carbs, Mediterranean, DASH, dairy-free,
gluten-free, wheat-free, egg-free, milk-free, peanut-free, tree-nut-free, soy-free, fish-free,
shellfish-free, pork-free, red-meat-free, crustacean-free, celery-free, mustard-free, sesame-free,
lupine-free, mollusk-free, alcohol-free, no-oil-added, no-sugar-added, sulfite-free, fodmap-free, kosher,
alcohol-cocktail, immuno-supportive ]
CautionLabel:
type: string
enum: [ gluten, wheat, eggs, milk, peanuts, tree-nuts, soy, fish, shellfish, sulfites, fodmap ]
CuisineType:
type: string
enum: [ "american", "asian", "british", "caribbean", "central europe", "chinese", "eastern europe", "french",
"greek", "indian", "italian", "japanese", "korean", "kosher", "mediterranean", "mexican",
"middle eastern", "nordic", "south american", "south east asian", "world" ]
MealType:
type: string
enum: [ "breakfast", "brunch", "lunch/dinner", "lunch", "dinner", "snack", "teatime" ]
DishType:
type: string
enum: [ "alcohol cocktail", "biscuits and cookies", "bread", "casserole", "cereals", "condiments and sauces",
"desserts", "drinks", "egg", "ice cream and custard", "main course", "pancake", "pasta", "pastry",
"pies and tarts", "pizza", "preps", "preserve", "salad", "sandwiches", "seafood", "side dish", "soup",
"special occasions", "starter", "sweets" ]
MetabolicProfile:
description: (BETA only) Collection of parameters describing a target user's metabolic profile
type: "object"
properties:
gender:
$ref: '#/components/schemas/Gender'
conditions:
type: array
items:
$ref: '#/components/schemas/Condition'
height:
type: number
weight:
type: number
age:
type: number
activity-level:
$ref: '#/components/schemas/ActivityLevel'
Gender:
description: User gender
type: string
enum: [ male, female ]
Condition:
description: Physical or medical condition
type: string
enum: [ pregnant, lactating ]
ActivityLevel:
description: |
| Activity level | Description |
|---------------------|-------------|
| `sedentary` | Most of the day spent sitting; example: office worker getting little or no exercise |
| `moderately-active` | Regular daily physical exercise; example: construction worker or person running one hour daily |
| `vigorously-active` | Intense daily physical exercise; example: agricultural worker (non mechanized) or person swimming two hours daily |
| `extremely-active` | Extreme daily physical effort; example: competitive cyclist |
type: string
enum: [ sedentary, moderately-active, vigorously-active, extremely-active ]
Values:
description: Recommended daily allowance and/or intake upper limit, in nutrient-specific units
type: object
properties:
recommended:
description: Recommended daily allowance, if defined
type: number
limit:
description: Tolerable upper limit on nutrient intake, if defined
type: number
NutrientTag:
description: See *Nutrient Guide*
type: string
examples:
7-Day-Plan-with-Allergens:
description: 7 Day Allergens descriptor
value:
size: 7
plan:
accept:
all:
- health:
- SOY_FREE
- FISH_FREE
- MEDITERRANEAN
fit:
ENERC_KCAL:
min: 1000
max: 2000
SUGAR.added:
max: 20
exclude:
- http://www.edamam.com/ontologies/edamam.owl#recipe_x
- http://www.edamam.com/ontologies/edamam.owl#recipe_y
- http://www.edamam.com/ontologies/edamam.owl#recipe_z
sections:
Breakfast:
accept:
all:
- dish:
- drinks
- egg
- biscuits and cookies
- bread
- pancake
- cereals
- meal:
- breakfast
fit:
ENERC_KCAL:
min: 100
max: 600
Lunch:
accept:
all:
- dish:
- main course
- pasta
- egg
- salad
- soup
- sandwiches
- pizza
- seafood
- meal:
- lunch/dinner
fit:
ENERC_KCAL:
min: 300
max: 900
Dinner:
accept:
all:
- dish:
- seafood
- egg
- salad
- pizza
- pasta
- main course
- meal:
- lunch/dinner
fit:
ENERC_KCAL:
min: 200
max: 900
Vegan-plan:
description: Vegan meal plan descriptor
value:
size: 2
plan:
accept:
all:
- health:
- VEGAN
- cuisine:
- Mediterranean
fit:
ENERC_KCAL:
min: 1800
max: 2200
PROCNT:
min: 50
max: 300
sections:
Breakfast: {}
Lunch:
exclude:
- http://www.edamam.com/ontologies/edamam.owl#recipe_x
- http://www.edamam.com/ontologies/edamam.owl#recipe_y
- http://www.edamam.com/ontologies/edamam.owl#recipe_z
sections:
Starter: {}
Main: {}
Dessert: {}
Dinner:
exclude:
- http://www.edamam.com/ontologies/edamam.owl#recipe_a
- http://www.edamam.com/ontologies/edamam.owl#recipe_b
- http://www.edamam.com/ontologies/edamam.owl#recipe_c
sections:
Main: {}
Dessert: {}
Vegan-plan-assignment:
description: Vegan meal plan, 2-day selection
value:
status: OK
selection:
- sections:
Breakfast:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_1
_links:
self:
title: Recipe №1
href: https://test-cluster.edamam.com/api/recipes/v2/1?type=public
Lunch:
sections:
Starter:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_2
_links:
self:
title: Recipe №2
href: https://test-cluster.edamam.com/api/recipes/v2/2?type=public
Main:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_3
_links:
self:
title: Recipe №3
href: https://test-cluster.edamam.com/api/recipes/v2/3?type=public
Dessert:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_4
_links:
self:
title: Recipe №4
href: https://test-cluster.edamam.com/api/recipes/v2/4?type=public
Dinner:
sections:
Main:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_5
_links:
self:
title: Recipe №5
href: https://test-cluster.edamam.com/api/recipes/v2/5?type=public
Dessert:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_6
_links:
self:
title: Recipe №6
href: https://test-cluster.edamam.com/api/recipes/v2/6?type=public
- sections:
Breakfast:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_7
_links:
self:
title: Recipe №7
href: https://test-cluster.edamam.com/api/recipes/v2/7?type=public
Lunch:
sections:
Starter:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_8
_links:
self:
title: Recipe №8
href: https://test-cluster.edamam.com/api/recipes/v2/8?type=public
Main:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_9
_links:
self:
title: Recipe №9
href: https://test-cluster.edamam.com/api/recipes/v2/9?type=public
Dessert:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_10
_links:
self:
title: Recipe №10
href: https://test-cluster.edamam.com/api/recipes/v2/10?type=public
Dinner:
sections:
Main:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_11
_links:
self:
title: Recipe №11
href: https://test-cluster.edamam.com/api/recipes/v2/11?type=public
Dessert:
assigned: http://www.edamam.com/ontologies/edamam.owl#recipe_12
_links:
self:
title: Recipe №12
href: https://test-cluster.edamam.com/api/recipes/v2/12?type=public
profile_Male_generic:
description: Male of unspecified age and build
value:
gender: male
profile_Male_complete:
description: Male profile, fully specified
value:
gender: male
height: 180
weight: 80
age: 26
activity-level: moderately-active
profile_Female_pregnant:
description: Pregnant female, 25, of unspecified build
value:
gender: female
conditions: [ pregnant ]
age: 25
profile_Female_complete:
description: Female profile, fully specified
value:
gender: female
conditions: [ lactating ]
height: 175
weight: 65
age: 20
activity-level: moderately-active
values_Male_generic:
description: Daily values for a male of unspecified age and build
value:
values:
PROCNT:
recommended: 34
WATER:
recommended: 2400
CHOCDF:
recommended: 130
FIBTG:
recommended: 31
F18D2CN6:
recommended: 12
F18D3CN3:
recommended: 1.2
VITA_RAE:
recommended: 600
limit: 1700
VITC:
recommended: 45
limit: 1200
VITD:
recommended: 15
limit: 100
TOCPHA:
recommended: 11
limit: 600
VITK1:
recommended: 60
THIA:
recommended: 0.9
RIBF:
recommended: 0.9
NIA:
recommended: 12
limit: 20
VITB6A:
recommended: 1
limit: 60
FOLDFE:
recommended: 300
limit: 600
VITB12:
recommended: 1.8
PANTAC:
recommended: 4
BIO:
recommended: 20
CHOLN:
recommended: 375
limit: 2000
CA:
recommended: 1300
limit: 3000
CR:
recommended: 25
CU:
recommended: 0.7
limit: 5
FLD:
recommended: 2000
limit: 10000
I:
recommended: 120
limit: 600
FE:
recommended: 8
limit: 40
MG:
recommended: 240
limit: 350
MN:
recommended: 1.9
limit: 6
MO:
recommended: 34
limit: 1100
P:
recommended: 1250
limit: 4000
SE:
recommended: 40
limit: 280
ZN:
recommended: 8
limit: 23
K:
recommended: 2500
NA:
recommended: 1200
CL:
recommended: 2300
limit: 3400
B:
limit: 11000
NI:
limit: 600
values_Female_pregnant:
description: Daily values for a pregnant female, 25, of unspecified build
value:
values:
PROCNT:
recommended: 71
CHOCDF:
recommended: 175
FIBTG:
recommended: 28
F18D2CN6:
recommended: 13
F18D3CN3:
recommended: 1.4
WATER:
recommended: 3000
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/edamam-recipes/refs/heads/main/openapi/edamam-meal-planner-v1-openapi.yml