(Version Retired)
h1. Introduction

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

Diet and Health Labels

Type Web Label API Parameter Deffinition
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-Fat2 low-fat-abs Less than 3g of fat per serving
Diet Balanced balanced Protein/Fat/Carb values in 15/35/50 ratio
Diet High-Fiber high-fiber More than 5g fiber per serving
Diet Low-Sodium low-sodium Less than 140mg Na per serving
Health No-sugar low-sugar No simple sugars – glucose, dextrose, galactose, fructose, sucrose, lactose, maltose
Health Sugar-conscious sugar-conscious Less than 4g of sugar per serving
Health Gluten gliten-free No ingredients containing gluten
Health Vegetarian vegetarian No meat, poultry, or fish
Health Vegan vegan No meat, poultry, fish, dairy, eggs or honey
Health Paleo paleo Excludes what are perceived to be agricultural products; grains, legumes, dairy products, potatoes, refined salt, refined sugar, and processed oils
Health Wheat-free wheat-free No wheat, can have gluten though
Health Dairy dairy-free No dairy; no lactose
Health Eggs egg-free No eggs or products containing eggs
Health Soy soy-free No soy or products containing soy
Health Fish fish-free No fish or fish derivatives
Health Shellfish shellfish-free No shellfish or shellfish derivatives
Health Tree Nuts tree-nut-free No tree nuts or products containing tree nuts
Health Low potassium low-potassium Less than 150mg per serving
Health Alcohol-free alcohol-free No alcohol used or contained
Health No oil added No-oil-added No oil added except to what is contained in the basic ingredients
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 Peanuts peanut-free No peanuts or products containing peanuts
Health Alcohol alcohol-free No alcohol used or contained in the recipe

Search

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

Search for recipes matching the specified query

The following parameters are part of the GET request URL:

Parameter Required Type Description
app_id yes string Your 3scale application ID
app_key yes string Your 3scale application key
q no* string Query text (required) For example q=chicken
from no integer First result index (default 0). Example: from=20
to no integer Last result index (exclusive, default from + 10). Example: to=30
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”
r no* string Returns information about a specific recipe based on its ID ie. -r=http://www.edamam.com/ontologies/edamam.owl%23recipe_637913ec61d9da69eb451818c3293df2
calories no range Calories per serving. The format is “gte L, lte U”, where integers L and U are the lower and upper bound, respectively, for the desired calories range. Either bound can be omitted.
Examples: “lte 600”, “gte 250”, “gte 250, lte 600”.
returns no Hits Query parameters and matching results
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

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 Recipe[] Matching results (Recipe objects)

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
level enum Difficulty level
summary string Short description
calories float Total energy, kcal
totalWeight float Total weight, g
ingredients Ingredient[] Ingredients list
totalNutrients NutrientInfo[] Total nutrients per serving
totalDaily NutrientInfo[] % daily value per serving
dietLabels enum[] Diet labels: “balanced”, “high-protein”, “high-fiber”, “low-fat”, “low-carb”, “low-sodium”
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”

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