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
• 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.
• Extraction of food entities with mesures and quantities from unstructured text

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.

*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

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:

Ingredient

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

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.

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

NutrientInfo

Ingredient

Full Recipe Analysis

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:

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:

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

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.

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

NutrientInfo

Ingredient

Food Text Analysis

Path: https://api.edamam.com/api/nutrition-data

Extracts information from a short unstructured food text – usually an ingredient line and returns:
- Structured data for the text – quantity, measure and food, if available
- Diet, health and allergen labels for the text

Food Text Analysis Request

You will use a GET request to submit the ingredient.

The API return nutritional analysis for the specified food text.

Example GET request

As an example, let’s say we want to extract information from the text ‘one large apple’. You should always include the quantity and the measure if you want to get nutrition for the line. Otherwise you will get only a food match. We then need to URL-encode this string. In this case, this means to just replace the spaces with %20, so it becomes “one%20large%20apple”. Please note, that the quotation marks aren’t part of the string.
Here is an example using curl:

Response

Example response

• Always try to include quantity and measure in the reques i.e.submit ‘one large apple’

Unique food text/igredient 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.

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 ingredient line and you will not be charged twice.
2. We have updated our database, the ingredient line 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 ingredient line you submitted has been change by you. As the ETag hash contains a “signature” for the text 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 text/igredient line has changed you can resubmit the ingredient line as new one (that is, without sending the If-None-Match header).

Licensing count example. You have analyzed 1000 ingredient lines the first month, 500 the second month and 10 the third month. The first month you will pay licensing fee for the nutrition of 1000 ingredient line, the second month for 1500 and the third for 1510. If you don’t analyze any more ingredient line after the third month you will pay licensing fee for the nutrition for the total of 1510 ingredient line every month thereafter.

Nutrients Codes and units

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.

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.