(Version Retired)
Welcome,
This is documentation for the nutritional API. It includes everything you will need to access all subscription plans.
Really, the only difference between the different plans is the detail of the output you we provide to you.
Happy coding!
Interfaces
Nutritional info
Path: https://api.edamam.com/api/nutrition-details
Returns nutritional information based on a POST
request of the recipe content
The following parameters are part of the POST
request URL:
Parameter | Required | Type | Description |
---|---|---|---|
app_id |
yes | String | Your 3scale application ID |
app_key |
yes | String | Your 3scale application key |
force |
no | Forces the re-evaluation of the recipe. The value, if any, is ignored. |
POST
Request
You will use a POST request to submit the recipe content—more specifically the recipe title and ingredient list.
The response the API will return will contain nutritional analysis for the recipe based on the information provided.
The contents of the request must be a JSON object with the following format:
Name | Required | Description |
---|---|---|
title |
yes | common name of the recipe |
ingr |
yes | ingredients (array of strings) |
summary |
no | a short description of the recipe |
yield |
no | number of servings |
ttime |
no | total time for preparation |
img |
no | image link (absolute) |
prep |
no | preparation instructions (free text) |
cuisine |
no | type of cuisine |
mealtype |
no | type of meal |
dishtype |
no | type of dish |
The request must contain the header
Content-Type: application/json
New recipes, resubmission and licensing count
Once you submit a recipe via the API you start paying Edamam a monthly licensing fee for each new analyzed recipe. Sometimes however, you may need to refresh the nutrition data for an already submitted recipe, in case you have lost the nutrition data for example. Submitting a recipe directly will count as analyzing a new recipe and you will be charged again licensing fee for the nutrition information. To avoid that we’ve implemented a system based on HTTP’s Etag mechanism.
First, each successfully processed recipe will also return a tag in the ETag
response header. This value must be preserved together with the recipe. Then, when resubmitting the recipe, you should include the value in the If-None-Match
request header.
There three possible outcomes:
- You are already using the most up to date version of the Edamam data. That is, you already have the newest version of the nutritional info. In this case, the system will return HTTP status code 304 – Not Modified. Note, that you can force the reevaluation in this case (for example if you lost your data) by passing the
force
parameter. Edamam will know that you are already paying license for the nutrition information for this recipe and you will not be charged twice. - We have updated our database, the recipe is processed again. In this case you’ll receive the possibly updated nutrition data as well as the updated
ETag
header. You should store that new value and use it for further resubmissions. - The recipe you submitted has been change by you. As the
ETag
hash contains a “signature” for the recipe content the system will respond with HTTP status code 409 – Conflict. In case you used the wrongETag
you can use correct the code, or if the recipe has changed you can resubmit the recipe as new one (that is, without sending theIf-None-Match
header).
Licensing count example. You have analyzed 100 recipes the first month, 50 the second month and 1 the third month. The first month you will pay licensing fee for the nutrition of 100 recipes, the second month for 150 and the third for 151. If you don’t analyze any more recipes after the third month you will pay licensing fee for the nutrition for the total of 151 recipes every month thereafter.
Example POST
request
Here is an example using curl:
This will send the recipe.json
file for processing.
Here is the contents of the recipe.json
file:
Response
HTTP Status code | Content-Type | Type | Description |
---|---|---|---|
200 OK | application/json | Recipe | Recipe object containing number of servings (yield), total calories for the recipe (calories), nutrient content by nutrient type (totalNutrients, totalDaily), diet and health classification (dietLabels, healthLabels) |
404 Not Found | text/html | HTML | The specified URL was not found or couldn’t be retrieved |
422 Uprocessable Entity | text/html | HTML | Couldn’t parse the recipe or extract the nutritional info |
555 | text/html | HTML | Recipe with insufficient quality to process correctly |
Example response
Here you can download a sample of the respons with
Types
Composite types are described in terms of their JSON representation.
Throughout descriptions, the following notation is used:
integer
,float
, andstring
stand for the JavaScript primitive typesinteger
,float
, andstring
, respectivelyenum
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 typeT
T[*]
stands for an object (associative map) whose every field (element) is of typeT
.
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 |
yield |
integer |
Number of servings |
calories |
float |
Total energy, kcal |
totalNutrients |
NutrientInfo[*] |
Total nutrients |
totalDaily |
NutrientInfo[*] |
% daily value |
dietLabels |
enum[] |
Diet labels: “balanced”, “high-protein”, “high-fiber”, “low-fat”, “low-carb”, “low-sodium” |
healthLabels |
enum[] |
Health labels: “vegan”, “vegetarian”, “dairy-free”, “low-sugar”, “low-fat-abs”, “sugar-conscious”, “fat free”, “gluten free”, “wheat free” |
NutrientInfo
field | type | description |
---|---|---|
uri |
string |
Ontology identifier |
label |
string |
Display label |
quantity |
float |
Quantity of specified units |
unit |
string |
Units |
Nutritional Label Definitions
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 |
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 |
n/a | low-fat-abs | Less than 3g of fat 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 < 250 mg AND potassium < 500 mg AND sodium: <500 mg |
Health |
Peanuts | peanut-free | No peanuts or products containing peanuts |
Health |
Alcohol | alcohol-free | No alcohol used or contained in the recipe |