Recipe Analysis and Food Database API Documentation

Release notes

  • This version of the API released on August 14 2017 replaces the previous version of the API.
  • You can find documentation for the depreciated API here.
  • If you have built an application before August 14 it will operate as usual. We will fully depreciate the old API by August 2018 and you will have time to migrate to the new API by then.

Recipe Analysis and Food Database

This API covers all key use cases related to nutrition data search and analysis. In addition it employs NLP (Natural Language Processing) which allows for extraction of food entities from unstructured text.

Covered Use Cases

  • Search for a food by keyword, food name or UPC/Barcode
  • Extraction of food entities with mesures and quantities from unstructured text
  • Sourcing of nutrition facts for a given food, including: macro and micro nutrients, allergen labels, lifestyle and health labels
  • Full analysis of food recipes in real time – entity extraction, measure and quantity extraction with computation of the aplicable nutrition for the recipe and applicable health and diet labels. Finally it adjusts quantity for certain ingredients to account for the cooking pocess. For example it calculates oil absorption for fried recipes, excludes solids from stock and broth recipes, calculates marinate absorption for marinates and much more.

Food Database Requests

Parse requests: https://api.edamam.com/api/food-database/parser

Food Database Text Search and Complex NLP Search

The parser access point handles both simple text search for foods and complex unstructured text submitions for entity extraction using NLP. The response to parser requests changes depending on the type of API plan an account has:

  • Basic food search request returnes database matches for the search string which was submitted.
  • An NLP entity extraction request returns parsed food entities and quantities from the text submitted.
  • Complex NLP search request returns parsed foods and quantities from the text submitted and then uses the parsed data to return additional matches from the food database.

UPC or Barcode Search

Allows for search of an item based UPC/Barcode number.

Parser Request

You will use a GET request to access the Parser.

Parameter Required Type Description
app_id yes String Your 3scale application ID
app_key yes String Your 3scale application key
ingr yes* String The ingredient (don’t forget to URL-encode!)
upc yes* number The UPC or barcode number for the food
page no integer Lists results from the sellected page (20 per page)

*Either UPC or ingr should be present for a valid request

Example Parser request

Basic Text Search

As an example, let’s say we want to find matches in the food database for a red apple. We then need to URL-encode this string. In this case, this means to just replace the spaces with %20,so it becomes “red%20apple” Please note, that the quotation marks aren’t part of the string.
Here is an example using curl:

'https://api.edamam.com/api/food-database/parser?ingr=red%20apple&app_id={your app_id}&app_key={your app_key}&page=0'

NLP entity extraction

Let’s say we want to parse a line from a recipe “one large red apple”. If your plan allows entity extraction this request will parse the line for quantity and measure.

Here is an example using curl:

'https://api.edamam.com/api/food-database/parser?ingr=one%20large%20red%20apple&app_id={your app_id}&app_key={your app_key}'

UPC or Barcode Search
This is a service allowing you to submit a UPC or barcode and find a match for it in the food database.

Here is an example using curl:
'https://api.edamam.com/api/food-database/parser?UPC={upc code}&app_id={your app_id}&app_key={your app_key}'

Parser Response

HTTP Status code Description
200 OK 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 The specified URL was not found or couldn’t be retrieved
422 Uprocessable Entity Couldn’t parse the recipe or extract the nutritional info
555 Recipe with insufficient quality to process correctly

Example response to NLP entity extraction WITH basic search

Example response to NLP entity extraction WITHOUT basic search

This respons is same as above with the Hints section staying empty. The goal here is just get named entities and quantity from the text.

Example response to Basic text search WITHOUT NLP entity extraction

Nutrition Data Requests

Nutrition Requests: https://api.edamam.com/api/food-database/nutrients

In the response to your parser request you receive the a food URI for each database match. Using the food URI and the measure URI which parser provides you can make a request to the ‘nutrients’ acces point. The ‘nutrients’ access points returns nutrition with diet and health labels for a given quantity of the food.

Nutrients Request

The contents of the request must be a JSON object with the following format:

Parameter Required Type Description
yield no number number of servings
ingredients yes Ingredient[] ingredients (array of Ingredient)

Ingredient

Parameter Required Type Description
quantity yes number The quantity of the ingredient
measureURI yes String one fo the measuement URI’s received in the parser response
foodURI yes String The food URI received in the parser response)

The API return nutritional analysis for the specified ingredient.

Example Nutrients request

You will use a POST request to access ‘nutrients’.

Here is an example using curl:

This will send the food.json file for processing.

Here is the contents of the food.json file:

Nutrients 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 Nutrients response

Nutirion

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

For ‘Nutritional Label Definitions’ consult the table at the bottom of this document

NutrientInfo

field type description
uri string Ontology identifier
label string Display label
quantity float Quantity of specified units
unit string Units

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

Recipe Analysis Requests

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.

Autocomplete Request

Edamam provides a convinient autocomplete functionality which can be used when searching for ingredients.

Path: http://api.edamam.com/auto-complete

The endpoint returns suggestions for the text submitted to it. Here is an example

http://api.edamam.com/auto-complete?q=rou&limit=10&app_id=${YOUR_APP_ID}&app_key=${YOUR_APP_KEY}

Recipe Analysis 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
url no url of the recipe’s location

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:

  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 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 wrong ETag you can use correct the code, or if the recipe has changed you can resubmit the recipe as new one (that is, without sending the If-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 ingredient level nutrition data

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”

For ‘Nutritional Label Definitions’ consult the table at the bottom of this document

NutrientInfo

field type description
uri string Ontology identifier
label string Display label
quantity float Quantity of specified units
unit string Units

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

Nutritional Label Definitions

Nutrition labels are shared by recipes and foods alike. They are assigned by Edamam based on the ingredients contained in the food label for CPG foods and by the basic ingredients of each recipe for recipes.

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 Alcohol alcohol-free No alcohol used or contained in the recipe
Health Alcohol-free alcohol-free No alcohol used or contained
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 Eggs egg-free No eggs or products containing eggs
Health Fish fish-free No fish or fish derivatives
Health Gluten gluten-free No ingredients containing gluten
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 Mustard-free mustard-free does not contain mustard or derivatives
Health n/a 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

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.