Natural Language for Nutrients
- 8 Minutes to read
- DarkLight
Natural Language for Nutrients
- 8 Minutes to read
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for 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:
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:
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).
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?