Natural Language for Nutrients
  • 8 Minutes to read
  • Dark
    Light

Natural Language for Nutrients

  • Dark
    Light

Article summary

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 InformationValue
Response FormatJSON
Requires AuthenticationYes
HTTP MethodPOST
Host Domainhttps://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


NameRequired for Authentication
DescriptionDefault ValuePremium Add-On Feature
query
string
YesQuery to be executed against.
No
num_servings
number
NoThe number of servings this dish yields. The nutrients when this food is logged will be divided by this number.
1No
aggregate
string
Nostring
nullNo
line_delimited
boolean
NoIf 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.
FALSENo
use_raw_foods
boolean
NoAllows parsing of uncooked variants.
FALSENo
include_subrecipe 
boolean
NoIf present, will return the recipe composition of the requested food (if exists).
FALSE
No
timezone 
string
NoThe timezone in which to parse relative time queries like "yesterday I ate x".
US/Eastern
No
consumed_at
string
NoISO 8601 compliant date format. Will overwrite any interpreted time contexts.
nullNo
use_branded_foods 
boolean
NoToggle interpretation of branded foods.
FalseNo
taxonomy
boolean
NoWhether to include taxonomy node id in the response.
FALSEYes
ingredient_statement
boolean
NoWhether to include nf_ingredient_statement.
FALSE
last_modified
boolean
NoWhether 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?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.