Models & Usage

Describes key information you need to know about the api response models

Nutritional Information

All foods that our database is allowed to return have at least the basics of their nutrition information, while many have fully complete nutrient profiles.

All Nutrients are stored on a food assuming a portion size of 100g

Portions are usually included, and the "default" portion will always come first in the array. If there are no portions, assume 100g serving:

A Default 100g portion

{
    "name": "100g",
    "quantity": 1,
    "suggestedQuantity": [
      1
    ],
    "weight": {
      "unit": "g",
      "value": 100
    }
}

Calculating Nutrient Amounts

As noted, each Nutrient stores the nutrition info assuming 100g.

Once you have selected the portion size you are going to calculate for, the formula for an individual item is as follows:

$$N = n * (w/100) * q$$

• N: final nutrient value

• n: nutrient amount from the nutrient

• w: value from the weight of the desired portion

• q: value from suggestedQuantity array.

  • Default suggested quantity comes first

  • If no suggested quantities, use 1

Example

Assuming we have retrieved a food with the following portion and nutrient information

{
    "id": "19283918235",
    "name": "Example food",
        ...,
    "portions": [
        {
            "weight": {
                "unit": "g",
                "value": 17
            },
            "name": "tbsp",
            "quantity": 1,
            "suggestedQuantity": [
                1
            ]
        }
    ],
    "nutrients": [
            ...,
        {
            "id": 1603211196548,
            "nutrient": {
                "name": "Energy",
                "unit": "KCAL",
                "shortName": "calories"
            },
            "amount": 294
        }
    ]
}

Example Calculation

# Extract the relevant information from the food data
weight_value = food_data['portions'][0]['weight']['value']
suggested_quantity = food_data['portions'][0]['suggestedQuantity'][0]  # Default suggested quantity comes first
nutrient_amount = food_data['nutrients'][0]['amount']

# Perform the calculation based on the formula
N = nutrient_amount * (weight_value / 100) * suggested_quantity
print(N)
>>> 49.98

Search Response

The search route will return a model with 2 top level fields, results and alternateNames

• Alternate Names: This is an array of common search terms related to what the user typed in some way. This is generally used to present a list of terms the user may have meant, sort of like the google did you mean... feature.

• Results: The array of results matching your search term

Our system sorts the results based on a set of complex rules, and the order is generally recommended as the best option across all search terms. With that said, we do return a number of scoring metrics our system uses internally, in case you want to develop your own second layer of sorting to match your needs better.

Using the Response

Once an item is selected from the search results, you can retrieve the fully formed information by using the its Reference Code, and the retrieve by reference code route

Names

There are various names available for most foods. Depending on the source of the food some names are available or not, but all foods will have a display name

• Display Name: The generally recommended name to show for the food item

• Long Name: The full name of the product item

• Short Name: If this item is one we internally manage and improve information on, this will be the shortened and simplified name of the item. For example the long name might be "Fred's Deliscious Chicken Breast, Bone In" and the short name might be "chicken"

The remaining names relate to scoring methods, and the score values returned. They are currently provided to give a head-start to a custom post-sorting method if you choose to implement one.

Scores

Various 0-1 float scores using different methods, weights, and algorithm combinations.

Nutrition Preview

To keep the response of search small, we do not return entire food details for all items. In order to assist with selecting the right item from search, we do provide a nutritionPreview field.

This field will have pre-calculated the correct amount of Calories for the default suggested portion size of the food. This can be displayed alongside search results for better clarity to users

Search Result Details Response

The search result route will return a model with 2 top level fields, results and alternateNames

• Alternate Names: This will currently be empty. Future features to come.

• Results: The array of results matching your search term

A (condensed) example of the response

{
    "alternatives": [],
    "results": [
        {
            "displayName": "Homemade Jam",
            "iconId": "",
            "type": "reference",
            "internalId": "77b8b508-8951-11ea-a893-77b0c1bdeca1",
            "internalName": "",
            "portions": [],
            "ingredients": [
                {
                    "id": "1603211317047",
                    "name": "HOMEMADE JAM",
                    "nutrients": [],
                    // and so on. See "Food Item" on this page
                }
            ]
        }
    ]
}

Calculating Nutrient Amounts For Result

For each ingredient, the same rules apply as the Food Item Calculating Nutrient Amounts

In the case of multiple ingredients, you will then execute the same calculation with the top-level SearchResult's portion size, and the combined total of each ingredient for each nutrient, and the combined weight in grams of ingredients to get the nutrition values per selected portion.