This is documentation for Version 2 of the Food Database API. If you need to see what are the changes from Version 1 please go to the changelog

Food Database

This API provides you with tools to find nutrition and diet data for generic foods, packaged foods and restaurant meals. In addition, it employs NLP (Natural Language Processing) which allows for extraction of food entities from unstructured text.

Covered Use Cases

• Search for 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
• Search for food by given nutrient quantity for 28 nutrients
• Search for foods within a given brand
• With the built-in food-logging context it allows for NLP requests for chatbots and natural language calorie counters

Food Database Requests

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

Food Database Text Search

The parser access point handles text search for foods as well as filters for the foods like presence specific nutrient content or exclusion of allergens

• Search for a phrase or keyword using NLP to get food entities from it.
• Get basic nutrition facts and ingredients for each food
• Search for food by given nutrient quantity for 28 nutrients
• Search for foods within a given brand
• With the build in food-logging context it allows for requests which do not contain quantity and suggest expected quantities for them.

Parser Request

You will use a GET request to access the Parser. Either UPC or ingr should be present for a valid request

When searching by keyword

When using food logging context

If you use the food logging context feature it will modify the NLP response in the following ways
- You can submit items without quantity. Edamam will try to match them and assign quantity to them based on expected serving size
- The API will return as results only foods ready for direct consumption – no raw meats, raw dry goods, like raw rice 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

Pagination

To obtain the next page, the API user should follow the “next” link from the “_links” section in the result JSON, which looks like this:

"_links" : {
    "next" : {
      "title" : "Next page",
      "href" : "https://api.edamam.com/api/food-database/v2/parser?..."
    }
}

Search by nutrient range

When searching by keyword you can also specify nutrient ranges by adding parameters in the following form:

nutrients[NTR]=RANGE where

NTR is one of: CA, CHOCDF, CHOLE, FAMS, FAPU, FASAT, FAT, FATRN, FE, FIBTG, FOLDFE, K, MG, NA, NIA, P, PROCNT, RIBF, SUGAR, THIA, TOCPHA, VITA_RAE, VITB12, VITB6A, VITC, VITD, VITK1 or ZN;

and

RANGE is in one of MIN+, MIN-MAX or MAX, where MIN and MAX are non-negative integer numbers.

For example:
nutrients[CA]=50+ means minimum 50 mg calcium, where ‘50+’ has to be properly encoded as ‘50%2B’
nutrients[FAT]=30 means maximum 30 g fat and
nutrients[FE]=5-10 means iron between 5 mg and 10 mg inclusive

You can combine more than one nutrient ranges in a search requests

Category and CategoryLabel Parameters

Category is a parameter that can be used when making a request in order to narrow down the results. They will narrow the results according to the following:

CategoryLabel is another parameter that can be used to narrow down search results based on a broader criteria than Category. The following can be used for this parameter:

Example Parser request

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/v2/parser?ingr=red%20apple&app_id={your app_id}&app_key={your app_key}'

NOTE: Please make sure you use the credentials you created for this exact API as they are app and plan specific. The ${ } notation is to signify the type of input and should NOT to be included in the request itself.

With ‘food-logging’ turned on:

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

Parser Response

Parsed

NOTE: The ‘parsed’ section of the response contains the direct result from NLP handling of the request with it broken down into quantity/measure/food. This data then is used to produce the results from the ‘hints’ section.

Hints

Example response to text search

*Nutrition Data Requests

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

In the response to your parser request you receive the a food ID for each database match. Using the food ID and the measure URI which parser provides you can make a request to the nutrients access 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 Parser response for each food contains all specialized measures for this food. For example if an apple has a specific unit named ‘slice’ it will come with the response from the API.

In addition to the units provided by the API Edamam supports virtually any weight and volume measures for all foods. Edamam does not return them in the API as it makes the response redundant and cumbersome.

Here is a list of the standard supported measures which can be used in addition the measures returned with the food:

A given measure may or may not contain a field “qualified”. This field contains possible measure qualifiers for the basic measure with each of them having its own URI. For example for the item ‘apple’ one of the measures is ‘whole’ with qualifiers ‘large’, ‘small’ etc.

When submitted together with the measure URI the qualifier URI changes the weight of the basic measure.

The API returns nutritional analysis for the specified ingredient.

Each food comes with a list of specialized units which belong to it. For example if an apple has a specific unit named slice it will come with the response from the API.

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 are the contents of the food.json file:

{
  "ingredients": [
    {
      "quantity": 1,
      "measureURI": "http://www.edamam.com/ontologies/edamam.owl#Measure_unit",
      "foodId": "food_bnbh4ycaqj9as0a9z7h9xb2wmgat"
    }
  ]
}

When a qualifier is available for a given measure it can be used in the following way:

{
  "ingredients": [
    {
      "quantity": 1,
      "measureURI": "http://www.edamam.com/ontologies/edamam.owl#Measure_unit",
      "foodId": "food_bnbh4ycaqj9as0a9z7h9xb2wmgat",
      "qualifiers": [ "http://www.edamam.com/ontologies/edamam.owl#Qualifier_large" ]
    }
  ]
}

Nutrients Response

Example Nutrients response

Nutrition

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

NutrientInfo

Ingredient

UPC or Barcode Search

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

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/v2/parser?upc={upc code}&app_id={your app_id}&app_key={your app_key}'

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}

Menu Search Requests

Overview

This endpoint search through our menu-items (aka “restaurant-foods”). In addition to full text search and health-labels restrictions (both similar to the parser/ingr combination in the food-database,) the menu search allows for geo-distance searching with a center point and distance.

The center of a menu search can be specified via a US postal code or via geo-coordinates (lat/lon pair). The search radius can be specified as a number, in miles by default, or as number + unit (for example: 6=6miles, 6km=6kilometers). The restaurants that offer a matching menu-item and fall within the search radius, receive a boost to their match score the closer they are to the center.

Use case

The use case assumes the user is located at the center and searches for the nearest restaurants (within a specified distance) offering matching foods. The foods can be spefied by full-text search and/or health-labels restriction.

On a more technical level, the API call finds the foods that match the restrictions and boosts the scores according to proximity to the center. The results outside the dist (distance) radius are not boosted, but are still returned.

Each API call can visualize the markers on a map. To open the visualization, find the
“map.jsp” link (_links.map in the json structure) at the end of the API page and open it in a browser, e.g.
http://menus.edamam.com/map.jsp?markers=1

Search request

You will use a GET request to access the Search. The parameter q must be specified.

Example Search request

As an example, let’s say we want to find nearest restaurants offering “caesar salad”.
We then need to URL-encode this string. In this case, this means to just replace the spaces with %20,so it becomes “caesar%20salad”. Please note, that the quotation marks aren’t part of the string.

Let’s also assume that our postal code is “19103” and we are looking for restaurants no farther than 10 miles.
Here is an example GET request (the url can be entered via a browser as well):

https://api.edamam.com/api/menu-items/v2/search?q=caesar%20salad&postal=19103&dist=10&app_id={your app_id}&app_key={your app_key}

Search Response

Hints

Example response to text search

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.

Nutritional labels (Health labels) used by the Menu items

The Nutritonal labels for menu items are a subset of those for foods and recipes. The following labels are supported:

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.