Use this API to populate any search interface, including autocomplete, with common foods and branded foods from Nutritionix. This searches our entire database of 600K+ foods. Once you select the food from the autocomplete interface, make a separate API request to look up the nutrients of the food.
Resource Information
Add the resource information as follows:
| Resource Information | Value |
|---|---|
| Response Format | JSON |
| Requires Authentication | Yes |
| HTTP Method | GET |
| Host Domain | https://trackapi.nutritionix.com |
| Endpoint | /v2/search/instant |
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 | Yes | Query to be executed against. | No | |
branded | No | Determines whether to include branded foods (grocery and restaurant) in the results. | True | No |
brand_ids | No | A list of brand ids to filter by. array[string], accepts an array of Nutritionix brand IDs to restrict search results to only include those brands. | null | No |
branded_type | No | Brand type to filter branded results by. 1=Restaurant, 2=Grocery. Null specifies no filtering. | null | No |
branded_region | No | Region id to filter branded results by. 1=US, 2=UK. null specifies no region filtering and only US returned. | null | No |
branded_food_name_only boolean | No | Search branded foods by only item name, not by a combo of item name and brand name. | No | |
common | No | Whether to include common food results. | No | |
common_general | No | Include common foods without grocery or restaurant tag. Applied only if ‘common’ field is set to true. | No | |
common_grocery | No | Include common grocery foods. Applied only if ‘common’ field is set to true. | No | |
common_restaurant | No | Include common restaurant foods. Applied only if ‘common’ field is set to true. | No | |
claims | No | Whether to include food label claims array. | False | Yes |
claims_query | No | An array of food labels claims that all must be true for each food in the results. | null | Yes |
taxonomy | No | Determines whether to include taxonomy node id in the results where one exists. | False | Yes |
taxonomy_node_id | No | Filters results to only those with the specified taxonomy node id. | null | Yes |
detailed_nutrients
| No | When exists, the value(s) for the specified nutrient(s) in the array are to be returned for all the items in the response. Limit up to 3 nutrients. | null | Yes |
The following table describes the operators that can used in queries to filter data:
Operator | Description |
|---|---|
gte | This operator indicates greater than or equal to. In the case of an input value entered through the 'gte' operator, the system returns all the results where the property's value is equal to or greater than the specified value. This operator can be used along with operators such as lt or lte. For example. "gte":"12". |
lte | This operator indicates less than or equal to. In the case of an input value entered through the 'lte' operator, the system returns all the results where the property's value is equal to or lesser than the specified value. This operator can be used along with operators such as gt or gte. For example. "lte":"12". |
Request
In the request, send the following details:
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://trackapi.nutritionix.com/v2/search/instant/?query=hamburger',
'headers': {
'Content-Type': 'application/json',
'x-app-id': ,
'x-app-key':
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Response
Returns in JSON format.
{
"common": [
{
"food_name": "hamburger",
"serving_unit": "sandwich",
"tag_name": "hamburger",
"serving_qty": 1,
"common_type": null,
"tag_id": "608",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/608_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburgers",
"serving_unit": "sandwich",
"tag_name": "hamburger",
"serving_qty": 1,
"common_type": null,
"tag_id": "608",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/608_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburger bun",
"serving_unit": "hamburger bun",
"tag_name": "hamburger bun",
"serving_qty": 1,
"common_type": null,
"tag_id": "226",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/226_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "soy hamburger",
"serving_unit": "veggie burger on bun",
"tag_name": "soy hamburger",
"serving_qty": 1,
"common_type": null,
"tag_id": "8268",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/44_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburger soup",
"serving_unit": "bowl (2 cups)",
"tag_name": "cheeseburger soup",
"serving_qty": 1,
"common_type": null,
"tag_id": "4818",
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"locale": "en_US"
},
{
"food_name": "beef hamburger",
"serving_unit": "sandwich",
"tag_name": "hamburger",
"serving_qty": 1,
"common_type": null,
"tag_id": "608",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/608_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburger buns",
"serving_unit": "hamburger bun",
"tag_name": "hamburger bun",
"serving_qty": 1,
"common_type": null,
"tag_id": "226",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/226_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "lean hamburger",
"serving_unit": "oz",
"tag_name": "lean hamburger",
"serving_qty": 3,
"common_type": null,
"tag_id": "9084",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/9084_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburger meat",
"serving_unit": "oz, cooked",
"tag_name": "ground beef",
"serving_qty": 4,
"common_type": null,
"tag_id": "47",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/47_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburger taco",
"serving_unit": "taco",
"tag_name": "beef taco",
"serving_qty": 1,
"common_type": null,
"tag_id": "2531",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/2531_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburger patty",
"serving_unit": "oz",
"tag_name": "hamburger patty",
"serving_qty": 3,
"common_type": null,
"tag_id": "2043",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/2043_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburger steak",
"serving_unit": "serving",
"tag_name": "salisbury steak",
"serving_qty": 1,
"common_type": null,
"tag_id": "1321",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/1321_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "double hamburger",
"serving_unit": "item",
"tag_name": "double hamburger",
"serving_qty": 1,
"common_type": null,
"tag_id": "3429",
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"locale": "en_US"
},
{
"food_name": "ground hamburger",
"serving_unit": "oz, cooked",
"tag_name": "ground beef",
"serving_qty": 4,
"common_type": null,
"tag_id": "47",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/47_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburger patties",
"serving_unit": "oz",
"tag_name": "hamburger patty",
"serving_qty": 3,
"common_type": null,
"tag_id": "2043",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/2043_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "grilled hamburger",
"serving_unit": "sandwich",
"tag_name": "hamburger",
"serving_qty": 1,
"common_type": null,
"tag_id": "608",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/608_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "lean hamburger meat",
"serving_unit": "oz",
"tag_name": "lean hamburger",
"serving_qty": 3,
"common_type": null,
"tag_id": "9084",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/9084_thumb.jpg"
},
"locale": "en_US"
},
{
"food_name": "hamburger vegetable soup",
"serving_unit": "bowl (2 cups)",
"tag_name": "hamburger vegetable soup",
"serving_qty": 1,
"common_type": null,
"tag_id": "7335",
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"locale": "en_US"
},
{
"food_name": "whole wheat hamburger buns",
"serving_unit": "roll",
"tag_name": "whole wheat hamburger roll",
"serving_qty": 1,
"common_type": null,
"tag_id": "5978",
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"locale": "en_US"
},
{
"food_name": "cheeseburger macaroni hamburger helper",
"serving_unit": "cup",
"tag_name": "hamburger helper",
"serving_qty": 1,
"common_type": 2,
"tag_id": "5226",
"photo": {
"thumb": "https://nix-tag-images.s3.amazonaws.com/5226_thumb.jpg"
},
"locale": "en_US"
}
],
"branded": [
{
"food_name": "Hamburger",
"serving_unit": "sandwich",
"nix_brand_id": "58c05bd9fc977da756c7a4fc",
"brand_name_item_name": "Milo's Hamburgers Hamburger",
"serving_qty": 1,
"nf_calories": 340,
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"brand_name": "Milo's Hamburgers",
"region": 1,
"brand_type": 1,
"nix_item_id": "c6405291f1393db78caf5a7e",
"locale": "en_US"
},
{
"food_name": "Double Hamburger",
"serving_unit": "grams",
"nix_brand_id": "513fbc1283aa2dc80c000273",
"brand_name_item_name": "Original Tommy's Hamburgers Double Hamburger",
"serving_qty": 333,
"nf_calories": 650,
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"brand_name": "Original Tommy's Hamburgers",
"region": 1,
"brand_type": 1,
"nix_item_id": "513fc9ca673c4fbc260046ed",
"locale": "en_US"
},
{
"food_name": "Triple Hamburger",
"serving_unit": "grams",
"nix_brand_id": "513fbc1283aa2dc80c000273",
"brand_name_item_name": "Original Tommy's Hamburgers Triple Hamburger",
"serving_qty": 398,
"nf_calories": 820,
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"brand_name": "Original Tommy's Hamburgers",
"region": 1,
"brand_type": 1,
"nix_item_id": "513fc9ca673c4fbc260046f1",
"locale": "en_US"
},
{
"food_name": "Hamburger with Thousand Island",
"serving_unit": "grams",
"nix_brand_id": "513fbc1283aa2dc80c000273",
"brand_name_item_name": "Original Tommy's Hamburgers Hamburger with Thousand Island",
"serving_qty": 270,
"nf_calories": 480,
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"brand_name": "Original Tommy's Hamburgers",
"region": 1,
"brand_type": 1,
"nix_item_id": "513fc9ca673c4fbc260046ef",
"locale": "en_US"
},
{
"food_name": "Hamburger Buns, Enriched",
"serving_unit": "bun",
"nix_brand_id": "51db37b1176fe9790a898466",
"brand_name_item_name": "Great Value Hamburger Buns, Enriched",
"serving_qty": 1,
"nf_calories": 100,
"photo": {
"thumb": "https://nutritionix-api.s3.amazonaws.com/536020b12ae36a5775c0a4da.jpeg"
},
"brand_name": "Great Value",
"region": 1,
"brand_type": 2,
"nix_item_id": "51c54cc997c3e6efadd61910",
"locale": "en_US"
},
{
"food_name": "Caliente Hamburger with Cheese",
"serving_unit": "grams",
"nix_brand_id": "513fbc1283aa2dc80c000273",
"brand_name_item_name": "Original Tommy's Hamburgers Caliente Hamburger with Cheese",
"serving_qty": 392,
"nf_calories": 780,
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"brand_name": "Original Tommy's Hamburgers",
"region": 1,
"brand_type": 1,
"nix_item_id": "ae4975996de9a319f07b74e7",
"locale": "en_US"
},
{
"food_name": "#3 Hamburger & Fries",
"serving_unit": "grams",
"nix_brand_id": "513fbc1283aa2dc80c000273",
"brand_name_item_name": "Original Tommy's Hamburgers #3 Hamburger & Fries",
"serving_qty": 506,
"nf_calories": 1140,
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"brand_name": "Original Tommy's Hamburgers",
"region": 1,
"brand_type": 1,
"nix_item_id": "513fc9ca673c4fbc260046af",
"locale": "en_US"
},
{
"food_name": "Hamburger Buns",
"serving_unit": "bun",
"nix_brand_id": "51db37b9176fe9790a898bde",
"brand_name_item_name": "Aunt Millie's Hamburger Buns",
"serving_qty": 1,
"nf_calories": 50,
"photo": {
"thumb": "https://assets.syndigo.com/1d9e9626-7ecb-4a0c-9cf9-33bc1ab39ab4"
},
"brand_name": "Aunt Millie's",
"region": 1,
"brand_type": 2,
"nix_item_id": "608969fb6c0df17d6a2a9dde",
"locale": "en_US"
},
{
"food_name": "Hamburger Buns, Sesame",
"serving_unit": "bun",
"nix_brand_id": "51db37b2176fe9790a89857c",
"brand_name_item_name": "Pepperidge Farm Hamburger Buns, Sesame",
"serving_qty": 1,
"nf_calories": 150,
"photo": {
"thumb": "https://assets.syndigo.com/c3c5ea04-97dd-4528-98da-8d8f9a2e69f2"
},
"brand_name": "Pepperidge Farm",
"region": 1,
"brand_type": 2,
"nix_item_id": "51d2fa7ecc9bff111580d5f9",
"locale": "en_US"
},
{
"food_name": "Hamburger Buns, Brioche Style",
"serving_unit": "bun",
"nix_brand_id": "51db37b9176fe9790a898bf4",
"brand_name_item_name": "Nature's Own Hamburger Buns, Brioche Style",
"serving_qty": 1,
"nf_calories": 170,
"photo": {
"thumb": "https://assets.syndigo.com/0528f135-f7d5-4d01-8212-1337ea3effde"
},
"brand_name": "Nature's Own",
"region": 1,
"brand_type": 2,
"nix_item_id": "5eb508297979d82e736cbd88",
"locale": "en_US"
},
{
"food_name": "Hamburger Buns, Enriched, White",
"serving_unit": "bun",
"nix_brand_id": "51db37b9176fe9790a898bdd",
"brand_name_item_name": "Kroger Hamburger Buns, Enriched, White",
"serving_qty": 1,
"nf_calories": 120,
"photo": {
"thumb": "https://assets.syndigo.com/3bbfd026-c983-4bb8-b4ce-b65b98a6c077"
},
"brand_name": "Kroger",
"region": 1,
"brand_type": 2,
"nix_item_id": "634e879fb12c290008618809",
"locale": "en_US"
},
{
"food_name": "Keto Friendly Hamburger Buns",
"serving_unit": "bun",
"nix_brand_id": "51db37ca176fe9790a8997de",
"brand_name_item_name": "Sam's Choice Keto Friendly Hamburger Buns",
"serving_qty": 1,
"nf_calories": 50,
"photo": {
"thumb": "https://nutritionix-api.s3.amazonaws.com/629df8f4dcb0f60009b64445.jpeg"
},
"brand_name": "Sam's Choice",
"region": 1,
"brand_type": 2,
"nix_item_id": "629df8f3dcb0f60009b64444",
"locale": "en_US"
},
{
"food_name": "Hamburger Buns, Classic, Extra Soft",
"serving_unit": "bun",
"nix_brand_id": "51db37c6176fe9790a899445",
"brand_name_item_name": "Wonder Hamburger Buns, Classic, Extra Soft",
"serving_qty": 1,
"nf_calories": 150,
"photo": {
"thumb": "https://assets.syndigo.com/4084e232-da5a-4432-b063-16ce5a9e863b"
},
"brand_name": "Wonder",
"region": 1,
"brand_type": 2,
"nix_item_id": "5ae2cca74f2975c172521eb9",
"locale": "en_US"
},
{
"food_name": "Hamburger Buns, Soft White",
"serving_unit": "bun",
"nix_brand_id": "51db37b2176fe9790a89857c",
"brand_name_item_name": "Pepperidge Farm Hamburger Buns, Soft White",
"serving_qty": 1,
"nf_calories": 140,
"photo": {
"thumb": "https://assets.syndigo.com/692abc94-3b98-4ea3-8f14-03d2fe926d2b"
},
"brand_name": "Pepperidge Farm",
"region": 1,
"brand_type": 2,
"nix_item_id": "51d2fa7ecc9bff111580d604",
"locale": "en_US"
},
{
"food_name": "Cheeseburger",
"serving_unit": "cup as pkgd",
"nix_brand_id": "51db37e7176fe9790a89a70e",
"brand_name_item_name": "Hamburger Helper Cheeseburger",
"serving_qty": 0.33000001311302185,
"nf_calories": 120,
"photo": {
"thumb": "https://nutritionix-api.s3.amazonaws.com/558067a15bb12ace64f4a3a7.jpeg"
},
"brand_name": "Hamburger Helper",
"region": 1,
"brand_type": 2,
"nix_item_id": "55806645a9bb06b364f24256",
"locale": "en_US"
},
{
"food_name": "Buns, Hamburger",
"serving_unit": "bun",
"nix_brand_id": "51db37b1176fe9790a8984d4",
"brand_name_item_name": "Publix Buns, Hamburger",
"serving_qty": 1,
"nf_calories": 130,
"photo": {
"thumb": "https://assets.syndigo.com/c95c05b7-2386-431a-93e8-5dcf74bc506b"
},
"brand_name": "Publix",
"region": 1,
"brand_type": 2,
"nix_item_id": "51c3b7f597c3e6d8d3b44ea3",
"locale": "en_US"
},
{
"food_name": "White Hamburger Buns",
"serving_unit": "bun",
"nix_brand_id": "51db37b7176fe9790a898a66",
"brand_name_item_name": "Sara Lee White Hamburger Buns",
"serving_qty": 1,
"nf_calories": 150,
"photo": {
"thumb": "https://nutritionix-api.s3.amazonaws.com/54ed9585a8480d8359a8c826.jpeg"
},
"brand_name": "Sara Lee",
"region": 1,
"brand_type": 2,
"nix_item_id": "54ed9519a8480d8359a8c810",
"locale": "en_US"
},
{
"food_name": "Original Hamburger",
"serving_unit": "grams",
"nix_brand_id": "59e11c705132aca01ae208b8",
"brand_name_item_name": "Harvey's Original Hamburger",
"serving_qty": 145,
"nf_calories": 360,
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"brand_name": "Harvey's",
"region": 1,
"brand_type": 1,
"nix_item_id": "c64028114548b2e5e45ca557",
"locale": "en_US"
},
{
"food_name": "Keto Hamburger Buns",
"serving_unit": "bun",
"nix_brand_id": "51db37b9176fe9790a898bed",
"brand_name_item_name": "Franz Keto Hamburger Buns",
"serving_qty": 1,
"nf_calories": 50,
"photo": {
"thumb": "https://nutritionix-api.s3.amazonaws.com/630dee598db9160006cee155.jpeg"
},
"brand_name": "Franz",
"region": 1,
"brand_type": 2,
"nix_item_id": "5ead1cef56cdcf657a1c4f49",
"locale": "en_US"
},
{
"food_name": "Coffee",
"serving_unit": "oz",
"nix_brand_id": "58c05bd9fc977da756c7a4fc",
"brand_name_item_name": "Milo's Hamburgers Coffee",
"serving_qty": 16,
"nf_calories": 0,
"photo": {
"thumb": "https://d2eawub7utcl6.cloudfront.net/images/nix-apple-grey.png",
"highres": null,
"is_user_uploaded": false
},
"brand_name": "Milo's Hamburgers",
"region": 1,
"brand_type": 1,
"nix_item_id": "c6405291ae43922e717560c9",
"locale": "en_US"
}
]
}
The results from the 'instant' endpoint are separated into 2 arrays each with a maximum 20 food items:
- branded: results from Nutritionix.com branded food database (restaurant brands and grocery brands).
- common: results from Nutritionix.com common food database (curated list of averaged food items that are not brand-specific).
Example Usage
- When you perform /search/instant/, the application displays the search drop-down based on the search criteria in the UI.
FAQs
How to filter search results based on their nutrients?
The /instant endpoint supports POST requests for filtering ranges of nutrients. For example, to filter items for matches with “burger” where calories (attr_id 208) is less than 500, you could submit a post query like this:
{
"query": "burger",
"full_nutrients": {
"208": {
"lte": 500
}
}
}
- gte = greater than
- lte = less than
How do you get nutrition information for foods in the /search/instant endpoint?
When you hit the /search/instant endpoint it returns two arrays: common and branded foods.
To get the nutrition information for common foods, take the food_name that is returned from any item in the "common" array, for example, "Big Mac" and POST that as the query to our /natural/nutrients endpoint.
To get the nutrition information for branded foods take the value of the “nix_item_id” attribute from any of the objects in the “branded” array, for example, 513fc9e73fe3ffd40300109f, and hit the /search/item endpoint.
What are the recommended debounce metrics when hitting the /v2/search/instant endpoint?
There are two important steps to ensure you are hitting the /search/instant endpoint effectively.
-
Requests to the /v2/search/instant endpoint should be debounced for at least 300ms. This will prevent an overload of requests to the endpoint as well as allow the client application some time before rendering the latest results.
-
You should not send requests to the instant endpoint until the user types at least 3 characters. Sending queries to instant at 1-2 characters can cause a substantially higher number of API queries to be made.
How do I filter out duplicate common foods from the /search/instant endpoint?
To provide the best experience to the end user, it is recommended to filter common food results on "tag_id". Common foods with the same tag_id have identical nutrition (for example, "Blackberry" and "Blackberries"). For best results, filter the results to show only one food per tag_id. Generally, the first one will be the most relevant based on the user search query.