Welcome,

This is documentation for the full nutritional API. It includes everything you will need to access both the free version of the API and the full version of the API.

Really, the only difference between the free version and the full one is the level of detail you get in the nutritional data.

In the free version you will receive nutritional labels plus calories and servings.

In the full version you will get also detailed data on 36 nutrients including fat, cholesterol, proteins, vitamins etc.

We expect that the free version will be sufficient for most use cases if you need the full one you can always apply for an upgrade.

Happy coding!

Interfaces

Nutritional info

Path: https://api.edamam.com/api/nutrient-info

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
extractOnly yes N/A This is an empty parameter required for backward compatibility
callback no String Callback parameter for JSONP. This will “envelop” the result in a JavaScript function call to the specified callback. Optional

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
level no level of difficulty
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

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

Types

Composite types are described in terms of their JSON representation.

Throughout descriptions, the following notation is used:

  • integer, float, and string stand for the JavaScript primitive types 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.

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

Label Definition
High protein More than 50% of total calories from proteins
Low carb Less than 20% of total calories from carbs
Low fat Less than 15% of total calories from fat
Balanced Protein/Fat/Carb values in 15/35/50 ratio
High fiber More than 5g fiber per serving
Low sodium Less than 140mg Na per serving
Low sugar No simple sugars — glucose, dextrose, galactose, fructose, sucrose, lactose, maltose
Sugar conscious Less than 4g of sugar per serving
Low fat abs Less than 3g of fat per serving
Gluten free Free of gluten containing foods
Wheat free No wheat, can have gluten though
Dairy-free No dairy; no lactose
Vegan No meat, poultry, fish, dairy, eggs or honey
Vegetarian No meat, poultry, or fish