Meal Planner API Documentation
Our Meal Planner API allows you to create, plan, and integrate meal plans into your mobile or web applications.
We have released the Meal Planner API! Use it to create, plan, and integrate meal plans, according to your specifications in your mobile or web applications!
The Edamam B2B API is accessed by sending HTTPS requests on specific URLs as described below. The base URL is https://api.edamam.com, and you obtain the full URL by appending request’s path to the base URL, for example, https://api.edamam.com/api/meal-planner/v1.
Our Meal Planner API allows you to create meal plans based on the millions of web recipes we have in our database, as well as with your own recipes. You can then integrate this information into your mobile or web applications.
The above OpenAPI specification for our API can be found here.
More information on OpenAPI can be found at: https://swagger.io/.
Example Request Body
The following body can be used for a 7 day meal plan with containing Soy-Free, Fish-Free, and Mediterranean labels. Please see the tables below for the full availability of labels for the respective fields:
{
"size": 7,
"plan": {
"accept": {
"all": [
{
"health": [
"SOY_FREE",
"FISH_FREE",
"MEDITERRANEAN"
]
}
]
},
"fit": {
"ENERC_KCAL": {
"min": 1000,
"max": 2000
},
"SUGAR.added": {
"max": 20
}
},
"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
}
}
}
}
}
}
Edamam Platform Assistant
The Edamam Platform Assistant is a chatbot integrated into four of Edamam’s API. This can provide an easy to use intuitive interface for your customers. The assistant allows you to submit natural language queries and receive back the necessary API calls needed in order to obtain the data requested by your query.
The Meal Planner API is integrated into this service, allowing the Edamam Platform Assistant to construct requests using all the parameters seen above. The Edamam Platform Assistant Documentation can be found here.
Accessing Recipes by URI
The resulting recipes available in the Meal Planner API can be accessed by using the “Search by Recipe URI” accesspoint in the Recipe Search API.
Your Meal Planner API credentials can be used to make these requests on the Recipe Search API.
HTTP Compression
Edamam servers support standard HTTP compression using gzip. Using compression can reduce the size of the response and thus, increase the transfer speed.
The client can include the following header, to indicate what compression methods it supports:
Accept-Encoding: gzip |
The server, then will include the following header to indicate the compressed response
Content-Encoding: gzip |
or it will omit it, if the response is not compressed.
For more information see here: http://en.wikipedia.org/wiki/Http_compression
Active User Tracking
Active User tracking is required for all Meal Planner API plans, unless stated differently. When Active user tracking is required the header for the user ID becomes mandatory or else an error will occur.
The user_id for each end-consumer is assigned by you and has to conform to the following restrictions.
Valid characters for user_ids. Allowed characters are: a-z/A-Z, 0-9, “-”, “_”, “.”. With a maximum length of 30 characters.
Nutrient Guide
The list of all of the nutrients that may be contained as part of a recipe’s nutritional information under the totalNutrients and the totalDaily section of the response. totalNutrients is the absolute nutrient amount, while totalDaily is the percent of daily recommended nutrient intake.
NTR Code | Name | Unit |
---|---|---|
SUGAR.added | Added sugar | g |
CA | Calcium, Ca | mg |
CHOCDF.net | Carbohydrate (net) | g |
CHOCDF | Carbohydrate, by difference | g |
CHOLE | Cholesterol | mg |
ENERC_KCAL | Energy | kcal |
FAMS | Fatty acids, total monounsaturated | g |
FAPU | Fatty acids, total polyunsaturated | g |
FASAT | Fatty acids, total saturated | g |
FATRN | Fatty acids, total trans | g |
FIBTG | Fiber, total dietary | g |
FOLDFE | Folate, DFE | µg |
FOLFD | Folate, food | µg |
FOLAC | Folic acid | µg |
FE | Iron, Fe | mg |
MG | Magnesium | mg |
NIA | Niacin | mg |
P | Phosphorus, P | mg |
K | Potassium, K | mg |
PROCNT | Protein | g |
RIBF | Riboflavin | mg |
NA | Sodium, Na | mg |
Sugar.alcohol | Sugar alcohols | g |
SUGAR | Sugars, total | g |
THIA | Thiamin | mg |
FAT | Total lipid (fat) | g |
VITA_RAE | Vitamin A, RAE | µg |
VITB12 | Vitamin B-12 | µg |
VITB6A | Vitamin B-6 | mg |
VITC | Vitamin C, total ascorbic acid | mg |
VITD | Vitamin D (D2 + D3) | µg |
TOCPHA | Vitamin E (alpha-tocopherol) | mg |
VITK1 | Vitamin K (phylloquinone) | µg |
WATER | Water | g |
ZN | Zinc, Zn | mg |
Nutrient Structure
The structure of the Nutrients based on what is under the totalNutrients and totalDaily sections of the response.
Field | Type | Description |
---|---|---|
uri |
string | Ontology identifier |
label |
string | Display label |
quantity |
float | Quantity of specified units |
unit |
string | Units |
Response Guide
The first sections of the response contain basic information on your search. “from” and “to” contain what number of the search results depicted in the current response. “count” contains the total number of search results found.
Hits
The “hits” section of the response contains all the search results for the recipe query based on relevance. These will include all the corresponding data for the recipes, as well as all the nutritional information.
Pagination
To obtain the next page, the API user should follow the “next” link from the “_links” section in the result JSON, which looks like this:
"_links" : {
"next" : {
"title" : "Next page",
"href" : "https://api.edamam.com/api/food-database/v2/parser?..."
}
}
CO2e (Carbon Dioxide Equivalent) Emissions
Edamam has developed the capability to search by CO2e effect per serving. This can be seen through the “co2EmissionsClass” parameter, which uses a rating system to classify the CO2e effect of recipes. The rating starts from A+ and goes down through A, B, C, D, E, F, to G being the highest emissions per serving for a recipe. When searching for recipes with a given rating, for example “B”, the Recipe Search API will return all recipes with a rating of B or better, i.e. A+, A, and B respectively. The new traffic light capability is published as a Beta feature on the Recipe Search API, meaning “beta=true” must be in the request in order to use the “co2EmissionsClass” parameter.
Ingredient Structure
The structure of the Ingredients based on what is under the ingredients section of the response.
Please note that some plans may not include all of the fields for the ingredient object.
Field | Type | Description |
---|---|---|
foodId |
string | Food identifier |
quantity |
float | Quantity of specified measure |
measure |
Measure | Measure |
weight |
float | Total weight, g |
food |
Food | Food |
foodCategory |
string | Shopping aisle category |
Image Sizes
You can narrow down the recipe search by specifying the “imageSize” parameter. By specifying from the possible values: THUMBNAIL, SMALL, REGULAR, and LARGE, the search will return recipes that have the specified image size available to use, i.e. using the LARGE value will return recipes that have the Large image size available (which might not be the same results as a query without the image sizes parameter defined, due to differing availability of image resolutions.)
These different sized images can then be seen in the “images” field of the JSON response. The following table shows all possible sizes.
Image Size | Dimensions |
---|---|
Thumbnail |
100×100 |
Small |
200×200 |
Regular |
300×300 |
Large |
600×600 |
Diet Labels
The list of all possible Diet Labels generated from the nutrient information on the recipes. These labels describe commonly used nutrient level aspects of the recipe.
Type | Web Label | API Parameter | Definition |
---|---|---|---|
Diet |
Balanced | balanced | Protein/Fat/Carb values in 15/35/50 ratio |
Diet |
High-Fiber | high-fiber | More than 5g fiber per serving |
Diet |
High-Protein | high-protein | More than 50% of total calories from proteins |
Diet |
Low-Carb | low-carb | Less than 20% of total calories from carbs |
Diet |
Low-Fat | low-fat | Less than 15% of total calories from fat |
Diet |
Low-Sodium | low-sodium | Less than 140mg Na per serving |
Health Labels
The list of all possible Health Labels generated from the ingredient information on the recipes. These labels describe commonly used ingredient level aspects of the recipe.
Type | Web Label | API Parameter | Definition |
---|---|---|---|
Health |
Alcohol-Cocktail | alcohol-cocktail | Describes an alcoholic cocktail |
Health |
Alcohol-Free | alcohol-free | No alcohol used or contained |
Health |
Celery-Free | celery-free | Does not contain celery or derivatives |
Health |
Crustcean-Free | crustacean-free | Does not contain crustaceans (shrimp, lobster etc.) or derivatives |
Health |
Dairy-Free | dairy-free | No dairy; no lactose |
Health |
DASH | DASH | Dietary Approaches to Stop Hypertension diet |
Health |
Egg-Free | egg-free | No eggs or products containing eggs |
Health |
Fish-Free | fish-free | No fish or fish derivatives |
Health |
FODMAP-Free | fodmap-free | Does not contain FODMAP foods |
Health |
Gluten-Free | gluten-free | No ingredients containing gluten |
Health |
Immuno-Supportive | immuno-supportive | Recipes which fit a science-based approach to eating to strengthen the immune system |
Health |
Keto-Friendly | keto-friendly | Maximum 7 grams of net carbs per serving |
Health |
Kidney-Friendly | kidney-friendly | Per serving – phosphorus less than 250 mg AND potassium less than 500 mg AND sodium less than 500 mg |
Health |
Kosher | kosher | Contains only ingredients allowed by the kosher diet. However it does not guarantee kosher preparation of the ingredients themselves |
Health |
Low Potassium | low-potassium | Less than 150mg per serving |
Health |
Low Sugar | low-sugar | No simple sugars – glucose, dextrose, galactose, fructose, sucrose, lactose, maltose |
Health |
Lupine-Free | lupine-free | Does not contain lupine or derivatives |
Health |
Mediterranean | Mediterranean | Mediterranean diet |
Health |
Mollusk-Free | mollusk-free | No mollusks |
Health |
Mustard-Free | mustard-free | Does not contain mustard or derivatives |
Health |
No oil added | No-oil-added | No oil added except to what is contained in the basic ingredients |
Health |
Paleo | paleo | Excludes what are perceived to be agricultural products; grains, legumes, dairy products, potatoes, refined salt, refined sugar, and processed oils |
Health |
Peanut-Free | peanut-free | No peanuts or products containing peanuts |
Health |
Pescatarian | pecatarian | Does not contain meat or meat based products, can contain dairy and fish |
Health |
Pork-Free | pork-free | Does not contain pork or derivatives |
Health |
Red-Meat-Free | red-meat-free | Does not contain beef, lamb, pork, duck, goose, game, horse, and other types of red meat or products containing red meat. |
Health |
Sesame-Free | sesame-free | Does not contain sesame seed or derivatives |
Health |
Shellfish-Free | shellfish-free | No shellfish or shellfish derivatives |
Health |
Soy-Free | soy-free | No soy or products containing soy |
Health |
Sugar-Conscious | sugar-conscious | Less than 4g of sugar per serving |
Health |
Sulfite-Free | sulfite-free | No Sulfites |
Health |
Tree-Nut-Free | tree-nut-free | No tree nuts or products containing tree nuts |
Health |
Vegan | vegan | No meat, poultry, fish, dairy, eggs or honey |
Health |
Vegetarian | vegetarian | No meat, poultry, or fish |
Health |
Wheat-Free | wheat-free | No wheat, can have gluten though |
Meal Types
List of all possible Meal Types. The meal types refer to the meals in a day the recipe is commonly consumed in.
Type | Value |
---|---|
mealType |
breakfast |
mealType |
brunch |
mealType |
lunch/dinner |
mealType |
snack |
mealType |
teatime |
Dish Types
List of all possible Dish Types. The dish types refer to the category of food the recipe would fall under.
Type | Value |
---|---|
dishType |
alcohol cocktail |
dishType |
biscuits and cookies |
dishType |
bread |
dishType |
cereals |
dishType |
condiments and sauces |
dishType |
desserts |
dishType |
drinks |
dishType |
egg |
dishType |
ice cream and custard |
dishType |
main course |
dishType |
pancake |
dishType |
pasta |
dishType |
pastry |
dishType |
pies and tarts |
dishType |
pizza |
dishType |
preps |
dishType |
preserve |
dishType |
salad |
dishType |
sandwiches |
dishType |
seafood |
dishType |
side dish |
dishType |
soup |
dishType |
special occasions |
dishType |
starter |
dishType |
sweets |
Cuisine Types
The list of all possible Cuisine Types. The cuisine types refer to the cuisine that the recipe would fall under.
Type | Value |
---|---|
cuisineType |
american |
cuisineType |
asian |
cuisineType |
british |
cuisineType |
caribbean |
cuisineType |
central europe |
cuisineType |
chinese |
cuisineType |
eastern europe |
cuisineType |
french |
cuisineType |
greek |
cuisineType |
indian |
cuisineType |
italian |
cuisineType |
japanese |
cuisineType |
korean |
cuisineType |
kosher |
cuisineType |
mediterranean |
cuisineType |
mexican |
cuisineType |
middle eastern |
cuisineType |
nordic |
cuisineType |
south american |
cuisineType |
south east asian |
cuisineType |
world |