(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 |
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 |