Nutrition Analysis API Documentation

We have released the OpenAPI specification for the Nutrition Analysis API!



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, for example, https://api.edamam.com/api/nutrition-details. \n \n This API covers all key use cases related to recipe and food text natural language processing and nutrition analysis. The API employs NLP (Natural Language Processing) which allows for extraction of food entities from unstructured text.

Covered Use Cases

  • Full analysis of food recipes in real time – entity extraction, measure and quantity extraction with computation of the applicable nutrition for the recipe and applicable health and diet labels. Finally, it adjusts quantity for certain ingredients to account for the cooking process. For example, it calculates oil absorption for fried recipes, excludes solids from stock and broth recipes, calculates marinate absorption for marinates and much more.
  • Extraction of food entities with measures and quantities from unstructured text.
  • Usage in chatbots transcribing natural speech to text.

 

The above OpenAPI specification for our API can be found here.
More information on OpenAPI can be found at: https://swagger.io/.

Food Logging

As stated in the specification, the food logging feature can be enabled by changing the “nutrition-type” parameter in the Nutrition Data GET request to “logging.” If you use the food logging context feature it will modify the NLP response in the following ways:
- You can submit items without quantity. We will try to match them and assign quantity to them based on expected serving size
- Only foods ready for direct consumption will be matched – no raw meats, raw dry goods or vegetables which need cooking for example
- Edamam can handle single items and two part compound items only – i.e. “chicken” or “rice AND chicken”. Make sure the URL is encoded properly

Nutrient Guide

The list of all of the nutrients that may be contained as part of a recipe’s nutritional information under the totalNutrients and the totalDaily section of the response. totalNutrients is the absolute nutrient amount, while totalDaily is the percent of daily recommended nutrient intake.

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

Nutrient Structure

The structure of the Nutrients based on what is under the totalNutrients and totalDaily sections of the response.

Field Type Description
uri string Ontology identifier
label string Display label
quantity float Quantity of specified units
unit string Units

Response Guide

Ingredient Structure

The structure of the Ingredients based on what is under the ingredients section of the response.

Please note that some plans may not include all of the fields for the ingredient object.

Field Type Description
foodId string Food identifier
quantity float Quantity of specified measure
measure Measure Measure
weight float Total weight, g
food Food Food
foodCategory string Shopping aisle category

Diet Labels

The list of all possible Diet Labels generated from the nutrient information on the recipes. These labels describe commonly used nutrient level aspects of the recipe.

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 Labels

The list of all possible Health Labels generated from the ingredient information on the recipes. These labels describe commonly used ingredient level aspects of the recipe.

Type Web Label API Parameter Definition
Health Alcohol-free alcohol-free No alcohol used or contained
Health Immune-Supportive immuno-supportive Recipes which fit a science-based approach to eating to strengthen the immune system
Health Celery-free celery-free Does not contain celery or derivatives
Health Crustcean-free crustacean-free Does not contain crustaceans (shrimp, lobster etc.) or derivatives
Health Dairy dairy-free No dairy; no lactose
Health Dietary Approaches to Stop Hypertension DASH
Health Eggs egg-free No eggs or products containing eggs
Health Fish fish-free No fish or fish derivatives
Health FODMAP free fodmap-free Does not contain FODMAP foods
Health Gluten gluten-free No ingredients containing gluten
Health Keto keto-friendly Maximum 7 grams of net carbs per serving
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 Mediterranean Mediterranean
Health Mustard-free mustard-free Does not contain mustard or derivatives
Health Low-fat-abs low-fat-abs Less than 3g of fat per serving
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 pecatarian 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

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:

  1. 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.
  2. 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.
  3. The recipe you submitted has been changed 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 have used the wrong ETag you can use correct the code, or if the recipe has changed you can resubmit the recipe as a new one (that is, without sending the If-None-Match header).

Licensing count example. You have analyzed 100 recipes in the first month, 50 the second month and 1 the third month. The first month you will pay a 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.

Unique food text/ingredient line, resubmission and licensing count

Once you submit an ingredient line via the API you start paying Edamam a monthly licensing fee for each new analyzed ingredient line. Sometimes however, you may need to refresh the nutrition data for an already submitted ingredient line, in case you have lost the nutrition data for example. Submitting an ingredient line directly will count as analyzing a new ingredient line, 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 ingredient line will also return a tag in the ETag response header. This value must be preserved together with the ingredient line. Then, when resubmitting the ingredient line, you should include the value in the If-None-Match request header.