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/search.

On success, the API returns HTTP code 200 OK and the body contains the result of the query in JSON format. In case of errors, the API returns an error code (e.g. 404 NOT FOUND). The body may contain useful information in HTML format. Client programs should use only the response codes, as the bodies are provided for the convenience of the client developers.

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.

Interfaces

Search

Path: https://api.edamam.com/search

The following parameters are part of the GET request URL:

Parameter	Required	Type	Description
q	yes *	string	Query text. For example q=chicken. *This or the r parameter are required
r	yes *	string	Returns information about a specific recipe based on its ID ie. r=http%3A%2F%2Fwww.edamam.com%2Fontologies%2Fedamam.owl%23recipe_9b5945e03f05acbf9d69625138385408 *This or the q parameter are required
app_id	yes	string	Your 3scale application ID
app_key	yes	string	Your 3scale application key (please note app_id/app_key are an ordered pair)
from	no	integer	First result index (default 0). Example: from=20. The maximum value of the “from” parameter is limitted by the number of results a plan is entitled to.
to	no	integer	Last result index (exclusive, default from + 10). Example: to=30
ingr	no	integer	Maximum number of ingredients. Example: ingr=5
diet	no	enum	Diet label: one of “balanced”, “high-protein”, “high-fiber”, “low-fat”, “low-carb”, “low-sodium”
health	no	enum	Health label: One of the Health api parameters listed in Diet and Health Labels table at the end of this documentation. Miltiple labels cab be submitted simultatniousely this way “health=peanut-free&health=tree-nut-free”
cuisineType	no	enum	The type of cuisine of the recipe. You can simultatniousely use saveral cuisines this way “cuisineType=chinese&cuisineType=indian”
mealType	no	enum	The type of meal a recipe belongs to – lunch, dinner, breakfast, snack
dishType	no	enum	The dish type a recipe belongs to – soup, salad, sandwich etc. You can simultatniousely use saveral dish types this way “dishType=soup&dishType=dessert”
calories	no	range	The format is calories=RANGE where RANGE is replaced by the value in kcal. RANGE is in one of MIN+, MIN-MAX or MAX, where MIN and MAX are non-negative integer numbers. The + symbol needs to be properly encoded. Examples: “calories=100-300” will return all recipes with which have between 100 and 300 kcal per serving.
time	no	range	Time range for the total cooking and prep time for a recipe . The format is time=RANGE where RANGE is replaced by the value in minutes. RANGE is in one of MIN+, MIN-MAX or MAX, where MIN and MAX are non-negative integer numbers. The + symbol needs to be properly encoded. Examples: “time=1%2B” will return all recipes with available total time greater then 1 minute
excluded	no	string	Excluding recipes with certain ingredients. The format is excluded=FOOD where FOOD is replaced by the name of the specific food you don’t want to be present in the recipe results. More than one food can be excluded at the same time. Example: excluded=vinegar&excluded=pretzel will exclude any recipes which contain vinegar or pretzels in their ingredient list
callback	no	string	Callback parameter for JSONP. This will “envelop” the result in a JavaScript function call to the specified callback. Optional
imageSize	no	string	This parameter narrows down the search of the recipes based on whether the image size defined is available for the recipe. The possible values are THUMBNAIL, SMALL, REGULAR, and LARGE. See Image Sizes below for dimension specifics and how to get the different sizes with the image URL. Having “imageSize=THUMBNAIL” will return recipes that have an image with THUMBNAIL dimensions available.

*Exactly one of these ( q / r ) must be present

Search by nutrient range

You can specify nutrient ranges by adding parameters in the following form:

nutrients[NTR]=RANGE where

NTR is one of: CA, CHOCDF, CHOLE, FAMS, FAPU, FASAT, FAT, FATRN, FE, FIBTG, FOLDFE, K, MG, NA, NIA, P, PROCNT, RIBF, SUGAR, THIA, TOCPHA, VITA_RAE, VITB12, VITB6A, VITC, VITD, VITK1 or ZN;

and

RANGE is in one of MIN+, MIN-MAX or MAX, where MIN and MAX are non-negative integer numbers.

For example:
nutrients[CA]=50+ means minimum 50 mg calcium, where ‘50+’ has to be properly encoded as ‘50%2B’
nutrients[FAT]=30 means maximum 30 g fat and
nutrients[FE]=5-10 means iron between 5 mg and 10 mg inclusive
note: always encode the URL i.e. nutrients[FE] is nutrients%5BFE%5D

You can combine more than one nutrient ranges in a search requests

NTR Code	Name	Unit	NTR Code	Name	Unit
CA	Calcium	mg	ENERC_KCAL	Energy	kcal
CHOCDF	Carbs	g	NIA	Niacin (B3)	mg
CHOLE	Cholesterol	mg	P	Phosphorus	mg
FAMS	Monounsaturated	g	PROCNT	Protein	g
FAPU	Polyunsaturated	g	RIBF	Riboflavin (B2)	mg
FASAT	Saturated	g	SUGAR	Sugars	g
FAT	Fat	g	THIA	Thiamin (B1)	mg
FATRN	Trans	g	TOCPHA	Vitamin E	mg
FE	Iron	mg	VITA_RAE	Vitamin A	æg
FIBTG	Fiber	g	VITB12	Vitamin B12	æg
FOLDFE	Folate (Equivalent)	æg	VITB6A	Vitamin B6	mg
K	Potassium	mg	VITC	Vitamin C	mg
MG	Magnesium	mg	VITD	Vitamin D	æg
NA	Sodium	mg	VITK1	Vitamin K	æg

Negative search (excluded ingredients)

You can specify foods which you don’t want to be present in the results which the search request returns.

This method is to be combined with the diet/health/allergen labels and is not designed to replace them.

Example: You want to get back only recipes which do not contain gluten, pork or yogurt. You will use the following exclusions then:

health=gluten-free&health=pork-free&excluded=yogurt&excluded=greek+yogurt

This request when combined with the proper “q=” term will result in recipes which do not contain plain yogurt or plain Greek yogurt and are also gluten and pork free.

However, if you wish to get recipes which do not contain milk or diary at all, you will be better off using the “dairy-free” or “milk-free” labels, as opposed to listing all possible foods containing lactose in the excluded ingredient

Here are some examples of how ingredient exclusion works:
• ‘Eggplant’ will exclude both eggplant and aubergine because they are synonyms
• ‘Chicken’ breast will exclude only chicken breast with skin but not ‘chicken’ or ‘skinless chicken breast’ as they are different foods nutritionally
• ‘spaghetti’ will exclude any type of normal pasta like macaroni or linguini as they are all the same food nutritionally just in different format. However, it will not exclude cooked pasta or whole wheat pasta as they are distinct from regular pasta.

The negative search also looks for the presence of the phrase in the “excluded=” parameter in the title of the recipe. So “excluded=yogurt” will exclude not only any recipes which contain the specific ingredient plain yogurt in their ingredient list but also for any recipes which contain the phrase yogurt in their title – for example “Greek Yogurt Dressing”

Example GET request

Here is an example using curl:

NOTE: Please make sure you use the credentials you created for this exact API as they are app and plan specific. The ${ } notation is to signify the type of input and should NOT to be included in the request itself.

Types

Composite types are described in terms of their JSON representation.

Throughout descriptions, the following notation is used:

• boolean, integer, float, and string stand for the JavaScript primitive types boolean, integer, float, and string, respectively
• enum stands for a string field that only takes on values from a pre-defined range (the range is specified where essential)
• T[] stands for an array of objects of type T
• T[*] stands for an object (associative map) whose every field (element) is of type T.

Hits

Field	Type	Description
q	string	Query text, as submitted
from	integer	First result index, as submitted
to	integer	Last result index, as submitted
count	integer	Number of results found
more	boolean	More that the maximum allowed number of results found
hits	Hit[]	Matching results (Hit objects)

Hit

Field	Type	Description
recipe	Recipe	Matching recipe (Recipe object)
bookmarked	boolean	Is this recipe bookmarked by the searching user?
bought	boolean	Is this recipe bought by the searching user?

Recipe

Note: Only a subset of the fields may be present, depending on the interface through which the recipe is obtained. Refer to the specific interface description for details

Field	Type	Description
uri	string	Ontology identifier
label	string	Recipe title
image	string	Image URL
source	string	Source site identifier
url	string	Original recipe URL
yield	integer	Number of servings
calories	float	Total energy, kcal
totalWeight	float	Total weight, g
ingredients	Ingredient[]	Ingredients list
totalNutrients	{string: NutrientInfo}	Total nutrients for the entire recipe. TotalNutrients/yield equals nutrients per serving
totalDaily	{string: NutrientInfo}	% daily value for the entire recipe. Total/Daily/yield equals nutrients per serving
dietLabels	enum[]	Diet labels: “balanced”, “high-protein”, “high-fiber”, “low-fat”, “low-carb”, “low-sodium” (labels are per serving)
healthLabels	enum[]	Health labels: “vegan”, “vegetarian”, “paleo”, “dairy-free”, “gluten-free”, “wheat-free”, “fat-free”, “low-sugar”, “egg-free”, “peanut-free”, “tree-nut-free”, “soy-free”, “fish-free”, “shellfish-free” (labels are per serving)

Image Sizes

You can narrow down the recipe search by specifying the Image Size 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 accessed by adding a suffix to the image file name following the table below.

Image Size	Dimensions	Suffix
Thumbnail	100×100	-s
Small	200×200	-m
Regular	300×300	no suffix
Large	600×600	-l

Adding no suffix gives the “regular” sized 300×300 image.

Example:

“https://www.edamam.com/web-img/1a7/1a7e8a7208e149b15e3d1ee51d77e7aa.jpg”
Returns a “regular” 300×300 image, while

“https://www.edamam.com/web-img/1a7/1a7e8a7208e149b15e3d1ee51d77e7aa-m.jpg”
Returns a “small” 200×200 image.

Ingredient

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

Please note that some plans may not include all of the fields for the ingredient object. Consult the API page for details and consider upgrading to a different plan if you need all the fields.

NutrientInfo

Field	Type	Description
uri	string	Ontology identifier
label	string	Display label
quantity	float	Quantity of specified units
unit	string	Units

Measure

Field	Type	Description
uri	string	Ontology identifier
label	string	Common name

Food

Field	Type	Description
foodId	string	Food identifier
label	string	Common name

Nutrients Codes and units

NTR Code	Name	Unit	NTR Code	Name	Unit
CA	Calcium	mg	ENERC_KCAL	Energy	kcal
CHOCDF	Carbs	g	NIA	Niacin (B3)	mg
CHOLE	Cholesterol	mg	P	Phosphorus	mg
FAMS	Monounsaturated	g	PROCNT	Protein	g
FAPU	Polyunsaturated	g	RIBF	Riboflavin (B2)	mg
SUGAR	Sugars	g	SUGAR.added	Sugars, added	g
FAT	Fat	g	FASAT	Saturated	g
FATRN	Trans	g	TOCPHA	Vitamin E	mg
FE	Iron	mg	VITA_RAE	Vitamin A	æg
FIBTG	Fiber	g	VITB12	Vitamin B12	æg
FOLDFE	Folate (Equivalent)	æg	FOLFD	Folate (food)	æg
K	Potassium	mg	VITC	Vitamin C	mg
MG	Magnesium	mg	VITD	Vitamin D	æg
NA	Sodium	mg	VITK1	Vitamin K	æg
VITB6A	Vitamin B6	mg	THIA	Thiamin (B1)	mg

Diet and Health Labels

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	Alcohol-free	alcohol-free	No alcohol used or contained
Health	Immune-Supportive	immuno-supportive	Recipes which fit a science-based approach to eating to strengthen the immune system
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	dairy-free	No dairy; no lactose
Health	Eggs	egg-free	No eggs or products containing eggs
Health	Fish	fish-free	No fish or fish derivatives
Health	FODMAP free	fodmap-free	Does not contain FODMAP foods
Health	Gluten	gluten-free	No ingredients containing gluten
Health	Keto	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	Lupine-free	lupine-free	Does not contain lupine or derivatives
Health	Mustard-free	mustard-free	Does not contain mustard or derivatives
Health	n/a	low-fat-abs	Less than 3g of fat per serving
Health	No oil added	No-oil-added	No oil added except to what is contained in the basic ingredients
Health	No-sugar	low-sugar	No simple sugars – glucose, dextrose, galactose, fructose, sucrose, lactose, maltose
Health	Paleo	paleo	Excludes what are perceived to be agricultural products; grains, legumes, dairy products, potatoes, refined salt, refined sugar, and processed oils
Health	Peanuts	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	shellfish-free	No shellfish or shellfish derivatives
Health	Soy	soy-free	No soy or products containing soy
Health	Sugar-conscious	sugar-conscious	Less than 4g of sugar per serving
Health	Tree Nuts	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 type, Dish type and Cuisine values

Type	API Parameter
mealType	Breakfast
mealType	Lunch
mealType	Dinner
mealType	Snack
mealType	Teatime
dishType	Alcohol-cocktail
dishType	Biscuits and cookies
dishType	Bread
dishType	Cereals
dishType	Condiments and sauces
dishType	Drinks
dishType	Desserts
dishType	Egg
dishType	Main course
dishType	Omelet
dishType	Pancake
dishType	Preps
dishType	Preserve
dishType	Salad
dishType	Sandwiches
dishType	Soup
dishType	Starter
cuisineType	American
cuisineType	Asian
cuisineType	British
cuisineType	Caribbean
cuisineType	Central Europe
cuisineType	Chinese
cuisineType	Eastern Europe
cuisineType	French
cuisineType	Indian
cuisineType	Italian
cuisineType	Japanese
cuisineType	Kosher
cuisineType	Mediterranean
cuisineType	Mexican
cuisineType	Middle Eastern
cuisineType	Nordic
cuisineType	South American
cuisineType	South East Asian