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