Natural Language for Nutrients

8 Minutes to read

Dark
Light

Natural Language for Nutrients

8 Minutes to read

Dark
Light

Article Summary

Share feedback

Thanks for sharing your feedback!

Use this API to get detailed nutrient breakdown of any natural language text. It can also be used in combination with the /search/instant endpoint to provide nutrition information for common foods.

Resource Information

Add the resource information as follows:

Resource Information	Value
Response Format	JSON
Requires Authentication	Yes
HTTP Method	POST
Host Domain	https://trackapi.nutritionix.com
Endpoint	/v2/natural/nutrients

Header

The header of the request contains parameters to authenticate the request. The request is authenticated only if the API authentication is enabled for you.

To authenticate the request, you must pass the “x-app-id” and “x-app-key”. For more information, see Understand Request Headers.

Parameters

Expand to see the parameters and description

Name	Required for Authentication	Description	Default Value	Premium Add-On Feature
query string	Yes	Query to be executed against.		No
num_servings number	No	The number of servings this dish yields. The nutrients when this food is logged will be divided by this number.	1	No
aggregate string	No	string	null	No
line_delimited boolean	No	If present, it expects only 1 food per line and will return an array of rules broken if there are any. i.e. 2+ foods on a line, no foods detected on this line, and so on.	FALSE	No
use_raw_foods boolean	No	Allows parsing of uncooked variants.	FALSE	No
include_subrecipe boolean	No	If present, will return the recipe composition of the requested food (if exists).	FALSE	No
timezone string	No	The timezone in which to parse relative time queries like "yesterday I ate x".	US/Eastern	No
consumed_at string	No	ISO 8601 compliant date format. Will overwrite any interpreted time contexts.	null	No
use_branded_foods boolean	No	Toggle interpretation of branded foods.	False	No
taxonomy boolean	No	Whether to include taxonomy node id in the response.	FALSE	Yes
ingredient_statement boolean	No	Whether to include nf_ingredient_statement.	FALSE
last_modified boolean	No	Whether to include the last_modified date.	FALSE

Request

In the request, send the following details:


var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://trackapi.nutritionix.com/v2/natural/nutrients',
  'headers': {
    'Content-Type': 'application/json',
    'x-app-id': ,
    'x-app-key': 
  },
  body: JSON.stringify({
    "query": "grape"
  })

Response

Returns in JSON format.


{
  "foods": [
    {
      "food_name": "grape",
      "brand_name": null,
      "serving_qty": 10,
      "serving_unit": "grapes",
      "serving_weight_grams": 49,
      "nf_calories": 33.81,
      "nf_total_fat": 0.08,
      "nf_saturated_fat": 0.03,
      "nf_cholesterol": 0,
      "nf_sodium": 0.98,
      "nf_total_carbohydrate": 8.87,
      "nf_dietary_fiber": 0.44,
      "nf_sugars": 7.59,
      "nf_protein": 0.35,
      "nf_potassium": 93.59,
      "nf_p": 9.8,
      "full_nutrients": [
        {
          "attr_id": 203,
          "value": 0.3528
        },
        {
          "attr_id": 204,
          "value": 0.0784
        },
        {
          "attr_id": 205,
          "value": 8.869
        },
        {
          "attr_id": 207,
          "value": 0.2352
        },
        {
          "attr_id": 208,
          "value": 33.81
        },
        {
          "attr_id": 209,
          "value": 0
        },
        {
          "attr_id": 210,
          "value": 0.0735
        },
        {
          "attr_id": 211,
          "value": 3.528
        },
        {
          "attr_id": 212,
          "value": 3.9837
        },
        {
          "attr_id": 213,
          "value": 0
        },
        {
          "attr_id": 214,
          "value": 0
        },
        {
          "attr_id": 221,
          "value": 0
        },
        {
          "attr_id": 255,
          "value": 39.4646
        },
        {
          "attr_id": 262,
          "value": 0
        },
        {
          "attr_id": 263,
          "value": 0
        },
        {
          "attr_id": 268,
          "value": 141.12
        },
        {
          "attr_id": 269,
          "value": 7.5852
        },
        {
          "attr_id": 287,
          "value": 0
        },
        {
          "attr_id": 291,
          "value": 0.441
        },
        {
          "attr_id": 301,
          "value": 4.9
        },
        {
          "attr_id": 303,
          "value": 0.1764
        },
        {
          "attr_id": 304,
          "value": 3.43
        },
        {
          "attr_id": 305,
          "value": 9.8
        },
        {
          "attr_id": 306,
          "value": 93.59
        },
        {
          "attr_id": 307,
          "value": 0.98
        },
        {
          "attr_id": 309,
          "value": 0.0343
        },
        {
          "attr_id": 312,
          "value": 0.0622
        },
        {
          "attr_id": 313,
          "value": 3.822
        },
        {
          "attr_id": 315,
          "value": 0.0348
        },
        {
          "attr_id": 317,
          "value": 0.049
        },
        {
          "attr_id": 318,
          "value": 32.34
        },
        {
          "attr_id": 319,
          "value": 0
        },
        {
          "attr_id": 320,
          "value": 1.47
        },
        {
          "attr_id": 321,
          "value": 19.11
        },
        {
          "attr_id": 322,
          "value": 0.49
        },
        {
          "attr_id": 323,
          "value": 0.0931
        },
        {
          "attr_id": 324,
          "value": 0
        },
        {
          "attr_id": 328,
          "value": 0
        },
        {
          "attr_id": 334,
          "value": 0
        },
        {
          "attr_id": 337,
          "value": 0
        },
        {
          "attr_id": 338,
          "value": 35.28
        },
        {
          "attr_id": 341,
          "value": 0
        },
        {
          "attr_id": 342,
          "value": 0.0343
        },
        {
          "attr_id": 343,
          "value": 0
        },
        {
          "attr_id": 344,
          "value": 0
        },
        {
          "attr_id": 345,
          "value": 0
        },
        {
          "attr_id": 346,
          "value": 0
        },
        {
          "attr_id": 347,
          "value": 0
        },
        {
          "attr_id": 401,
          "value": 1.568
        },
        {
          "attr_id": 404,
          "value": 0.0338
        },
        {
          "attr_id": 405,
          "value": 0.0343
        },
        {
          "attr_id": 406,
          "value": 0.0921
        },
        {
          "attr_id": 410,
          "value": 0.0245
        },
        {
          "attr_id": 415,
          "value": 0.0421
        },
        {
          "attr_id": 417,
          "value": 0.98
        },
        {
          "attr_id": 418,
          "value": 0
        },
        {
          "attr_id": 421,
          "value": 2.744
        },
        {
          "attr_id": 429,
          "value": 0
        },
        {
          "attr_id": 430,
          "value": 7.154
        },
        {
          "attr_id": 431,
          "value": 0
        },
        {
          "attr_id": 432,
          "value": 0.98
        },
        {
          "attr_id": 435,
          "value": 0.98
        },
        {
          "attr_id": 454,
          "value": 0.049
        },
        {
          "attr_id": 501,
          "value": 0.0054
        },
        {
          "attr_id": 502,
          "value": 0.0108
        },
        {
          "attr_id": 503,
          "value": 0.0054
        },
        {
          "attr_id": 504,
          "value": 0.0108
        },
        {
          "attr_id": 505,
          "value": 0.0132
        },
        {
          "attr_id": 506,
          "value": 0.0044
        },
        {
          "attr_id": 507,
          "value": 0.0049
        },
        {
          "attr_id": 508,
          "value": 0.0093
        },
        {
          "attr_id": 509,
          "value": 0.0049
        },
        {
          "attr_id": 510,
          "value": 0.0108
        },
        {
          "attr_id": 511,
          "value": 0.0637
        },
        {
          "attr_id": 512,
          "value": 0.0108
        },
        {
          "attr_id": 513,
          "value": 0.0108
        },
        {
          "attr_id": 514,
          "value": 0.0186
        },
        {
          "attr_id": 515,
          "value": 0.0397
        },
        {
          "attr_id": 516,
          "value": 0.0078
        },
        {
          "attr_id": 517,
          "value": 0.0392
        },
        {
          "attr_id": 518,
          "value": 0.0108
        },
        {
          "attr_id": 601,
          "value": 0
        },
        {
          "attr_id": 605,
          "value": 0
        },
        {
          "attr_id": 606,
          "value": 0.0265
        },
        {
          "attr_id": 607,
          "value": 0
        },
        {
          "attr_id": 608,
          "value": 0
        },
        {
          "attr_id": 609,
          "value": 0
        },
        {
          "attr_id": 610,
          "value": 0
        },
        {
          "attr_id": 611,
          "value": 0
        },
        {
          "attr_id": 612,
          "value": 0.0005
        },
        {
          "attr_id": 613,
          "value": 0.0225
        },
        {
          "attr_id": 614,
          "value": 0.0029
        },
        {
          "attr_id": 617,
          "value": 0.0034
        },
        {
          "attr_id": 618,
          "value": 0.0181
        },
        {
          "attr_id": 619,
          "value": 0.0054
        },
        {
          "attr_id": 620,
          "value": 0
        },
        {
          "attr_id": 621,
          "value": 0
        },
        {
          "attr_id": 626,
          "value": 0
        },
        {
          "attr_id": 627,
          "value": 0
        },
        {
          "attr_id": 628,
          "value": 0
        },
        {
          "attr_id": 629,
          "value": 0
        },
        {
          "attr_id": 630,
          "value": 0
        },
        {
          "attr_id": 631,
          "value": 0
        },
        {
          "attr_id": 636,
          "value": 1.96
        },
        {
          "attr_id": 645,
          "value": 0.0034
        },
        {
          "attr_id": 646,
          "value": 0.0235
        }
      ],
      "nix_brand_name": null,
      "nix_brand_id": null,
      "nix_item_name": null,
      "nix_item_id": null,
      "upc": null,
      "consumed_at": "2023-09-22T18:24:59+00:00",
      "metadata": {
        "is_raw_food": false
      },
      "source": 1,
      "ndb_no": 9132,
      "tags": {
        "item": "grape",
        "measure": null,
        "quantity": "10.0",
        "food_group": 3,
        "tag_id": 586
      },
      "alt_measures": [
        {
          "serving_weight": 126,
          "measure": "NLEA serving",
          "seq": 3,
          "qty": 1
        },
        {
          "serving_weight": 49,
          "measure": "grapes",
          "seq": 2,
          "qty": 10
        },
        {
          "serving_weight": 151,
          "measure": "cup",
          "seq": 1,
          "qty": 1
        },
        {
          "serving_weight": 5,
          "measure": "grape",
          "seq": 80,
          "qty": 1
        },
        {
          "serving_weight": 28.34,
          "measure": "oz",
          "seq": 81,
          "qty": 1
        },
        {
          "serving_weight": 100,
          "measure": "g",
          "seq": null,
          "qty": 100
        },
        {
          "serving_weight": 3.15,
          "measure": "tsp",
          "seq": 101,
          "qty": 1
        },
        {
          "serving_weight": 9.44,
          "measure": "tbsp",
          "seq": 102,
          "qty": 1
        }
      ],
      "lat": null,
      "lng": null,
      "meal_type": 3,
      "photo": {
        "thumb": "https://nix-tag-images.s3.amazonaws.com/586_thumb.jpg",
        "highres": "https://nix-tag-images.s3.amazonaws.com/586_highres.jpg",
        "is_user_uploaded": false
      },
      "sub_recipe": null,
      "class_code": null,
      "brick_code": null,
      "tag_id": null
    }
  ]
}

FAQs

How do you get the available serving sizes for a food?

POST https://trackapi.nutritionix.com/v2/natural/nutrients and look for the "alt_measures" array:

nutritionix-faq

Using the serving_weight parameter value from the alt_measure array, you can derive the nutrients in each serving by dividing that serving weight by the default returned serving weight of the food object, and multiplying by the full_nutrients array:

(foods.alt_measures.serving_weight / foods.serving_weight_grams) * full_nutrients

For example, if you hit natural API with "3 large eggs", the alt measures looks similar to this this:

nutritionix-faq

The full_nutrients array will include the nutrient values for 3 large eggs, which weigh 150g. As a quality assurance check, we now know that 150g of eggs has 214.5 calories.

Now, let's say the user only wants nutritionals for 1 small egg, instead of the original 3 large eggs. Instead of hitting the natural API again, you can calculate the new nutrition values by using the serving_weight in the alt_measures array. We know from alt_measures that 1 small egg is 38 grams. We know the nutrient values of 50g of eggs, so with some quick algebra we can calculate the nutrient values of any of the alt_measures.

There are a few different ways to do this and still get the same answer:

Method 1:

Take our original equation above:
(foods.alt_measures.serving_weight / foods.serving_weight_grams) * full_nutrients
So the calories of one 38g small egg would be, (38g/150g)*214.5kcal = 54.3kcal.

For development purposes, you can check your answer using our natural API and confirm that 38g egg is 54.3kcal.

Method 2:

If you want to have even more flexibility to calculate the nutrients for any arbitrary gram weight, divide the values in the full nutrients array by the foods.serving_weight_grams value, to get the nutrient values of 1 gram of the food (aka: "1g nutrients array"). In our 3 eggs example, you would divide the entire full nutrients array by 150g.

To calculate any arbitrary gram measures of eggs, you would multiply the desired gram value by the new "1g nutrients array". All of these calculations can be done on-the-fly in the client, no need to make additional API calls.

Important note about serving sizes:

If your UI allows the user to change the quantity of an item after hitting our natural API, it is important to maintain the original quantity value from our API to properly calculate any future user-defined derivations. In our same example above, we start with 3 large eggs. If the user changes the quantity to 2 large eggs, in the background you are generating a multiplier by dividing the user-defined quantity (2) by the original API quantity (3).

nutritionix-faq

The above image is an example from the "view basket" page of the Nutritionix Track app.

So the multiplier in this example would be (⅔). If you multiply the full nutrients array of 3 large eggs by ⅔ you will get the nutrients for 2 large eggs.

This same logic can be applied when the user edits a quantity of any alt_measure. Always perform a QA check by visiting our natural demo page and testing the values in your app against ours to make sure your math is right!

Was this article helpful?

What's Next

Instant Endpoint

Table of contents