Recipe Search API Documentation

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, like 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

For recipes in Spanish you need to access our Beta at Path: https://test-es.edamam.com/search

Search for recipes matching the specified query. Make sure your queries are in the correct language at each specific access point!

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
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. For example “peanut-free”, “tree-nut-free”, “soy-free”, “fish-free”, “shellfish-free”
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
*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 50mg calcium, where ‘50+’ has to be properly encoded as ‘50%2B’
nutrients[FAT]=30 means maximum 30g fat and
nutrients[FE]=5-10 means iron between 5mg and 10mg inclusive
note: always encode the URL i.e. nutrients[FE] is nutrients%5BFE%5D

You can combine more then 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 which 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 a presense of the phrase from 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.

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
params String[][] Effective parameters
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 NutrientInfo[] Total nutrients for the entire recipe
totalDaily NutrientInfo[] % daily value for the entire recipe
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)

Ingredient

Field Type Description
uri string Ontology identifier
quantity float Quantity of specified measure
measure Measure Measure
weight float Total weight, g
food Food Food

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
uri string Ontology 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 Celery-free celery-free does not contain celery or derivatives
Health Crustacean-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 Gluten gluten-free No ingredients containing gluten
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 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 pescatarian 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