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 VITA_RAE: recommended: 770 limit: 3000 VITC: recommended: 85 limit: 2000 VITD: recommended: 15 limit: 100 TOCPHA: recommended: 15 limit: 1000 VITK1: recommended: 90 THIA: recommended: 1.4 RIBF: recommended: 1.4 NIA: recommended: 18 limit: 35 VITB6A: recommended: 1.9 limit: 100 FOLDFE: recommended: 600 limit: 1000 VITB12: recommended: 2.6 PANTAC: recommended: 6 BIO: recommended: 30 CHOLN: recommended: 450 limit: 3500 CA: recommended: 1000 limit: 2500 CR: recommended: 30 CU: recommended: 1 limit: 10 FLD: recommended: 3000 limit: 10000 I: recommended: 220 limit: 1100 FE: recommended: 27 limit: 45 MG: recommended: 350 limit: 350 MN: recommended: 2 limit: 11 MO: recommended: 50 limit: 2000 P: recommended: 700 limit: 3500 SE: recommended: 60 limit: 400 ZN: recommended: 11 limit: 40 K: recommended: 2900 NA: recommended: 1500 CL: recommended: 2300 limit: 3600 B: limit: 20000 NI: limit: 1000 securitySchemes: basic: type: http scheme: basic