food.get.v2

Description

Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users.

The only storable values returned by this call are the food_id unique identifier and the one or more serving_id unique serving size identifier values.


Why are we introducing version 2?

On May 27, 2016 the USA Food and Drug Administration (FDA) published new rules on the new Nutrition Facts label for packaged foods to reflect new scientific information, including the link between diet and chronic diseases such as obesity and heart disease.

Manufacturers in the USA with $10 million or more in annual sales were required to switch to the new label by January 1, 2020; manufacturers with less than $10 million in annual food sales have until January 1, 2021 to comply.

More information can be found here: Changes to the Nutrition Facts Label

Please find more information on how to calcualte the %DV for your users: Dietary Supplement Label Database


What are the differences between food.get (v1) and food.get.v2?

food.get (v1) food.get.v2
The Vitamin A value is the percentage percentage of daily recommended.
It is based on a 2000 calorie diet.
The Vitamin A value is the raw value in micrograms (mcg).
It is up to the developer to calculate the %DV (Percent Daily Value)
The Vitamin C value is the percentage percentage of daily recommended.
It is based on a 2000 calorie diet.
The Vitamin C value is the raw value in milligrams (mg).
It is up to the developer to calculate the %DV
The Calcium value is the percentage of daily recommended.
It is based on a 2000 calorie diet.
The Calcium value is the raw value in milligrams (mg).
It is up to the developer to calculate the %DV
The Iron value is the percentage of daily recommended.
It is based on a 2000 calorie diet.
The Iron value is the raw value in milligrams (mg).
It is up to the developer to calculate the %DV
--- Vitamin D is the raw value in micrograms (mcg).
--- Added Sugars is the raw value in grams (g).
It is new for our food_type = "Brand"


Including Sub Categories (Premier Only):

An additional optional parameter named include_sub_categories is available to premier clients only. This parameter, of type Boolean should be specified as “true” in order to enable this feature.

When this parameter is included, the response will include the names of all sub categories associated with the food.

Flag Default Serving (Premier Only):

An additional optional parameter named flag_default_serving is available to premier clients only. This parameter, of type Boolean should be specified as “true” in order to enable this feature.

When this parameter is included, the response will flag one of the servings as the default serving (the suggested or most commonly chosen option).

Localization (Premier Only):

Two additional optional parameters named region and language are available to premier clients. More information can be found in the Localization guide.

Parameters

Required

Name Type Description
method String MUST be "food.get.v2"
food_id Long The ID of the food to retrieve.

Optional

Name Type Description
format String The desired response format. Valid reponse formats are "xml" or "json" (default value is "xml").

Response

The food element returned contains general information about the food item with detailed nutritional information for each available standard serving size.

The general information returned is:

  • food_id – the unique food identifier.
  • food_name – the name of the food, not including the brand name. E.G.: "Instant Oatmeal".
  • food_type – takes the value "Brand" or "Generic". Indicates whether the food is a brand or generic item – see food_type.
  • brand_name – the brand name, only when food_type is "Brand". E.G.: "Quaker".
  • food_url – URL of this food item on www.fatsecret.com.

Nutrient values for each food item are returned according to the standard serving sizes available. The elements returned for each standard serving size are:

  • serving_id – the unique serving identifier.
  • serving_description – the full description of the serving size. E.G.: "1 cup" or "100 g".
  • serving_url – URL of the serving size for this food item on www.fatsecret.com.
  • metric_serving_amount is a Decimal - the metric quantity combined with metric_serving_unit to derive the total standardized quantity of the serving (where available).
  • metric_serving_unit – the metric unit of measure for the serving size – either "g" or "ml" or "oz" – combined with metric_serving_amount to derive the total standardized quantity of the serving (where available).
  • number_of_units is a Decimal - the number of units in this standard serving size. For instance, if the serving description is "2 tablespoons" the number of units is "2", while if the serving size is "1 cup" the number of units is "1".
  • measurement_description – a description of the unit of measure used in the serving description. For instance, if the description is "1/2 cup" the measurement description is "cup", while if the serving size is "100 g" the measurement description is "g". Please note that this is only applicable for when food_type is "Generic" whereas for "Brand" the measurement description will always be "serving".

The complete nutritional information is returned - see nutrient


Example Return XML

<?xml version="1.0" encoding="utf-8" ?>
<food xmlns="http://platform.fatsecret.com/api/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://platform.fatsecret.com/api/1.0/ http://platform.fatsecret.com/api/1.0/fatsecret.xsd">
    <food_id>4384</food_id>
    <food_name>Plain French Toast</food_name>
    <food_type>Generic</food_type>
    <food_url>http://www.fatsecret.com/calories-nutrition/generic/french-toast-plain</food_url>
    <servings>
        <serving>
            <serving_id>16758</serving_id>
            <serving_description>regular slice</serving_description>
            <serving_url>http://www.fatsecret.com/calories-nutrition/generic/french-toast-plain?portionid=16758&portionamount=1.000</serving_url>
            <metric_serving_amount>65.000</metric_serving_amount>
            <metric_serving_unit>g</metric_serving_unit>
            <number_of_units>1.000</number_of_units>
            <measurement_description>regular slice</measurement_description>
            <calories>159</calories>
            <carbohydrate>20.02</carbohydrate>
            <protein>5.58</protein>
            <fat>6.13</fat>
            <saturated_fat>1.585</saturated_fat>
            <polyunsaturated_fat>1.578</polyunsaturated_fat>
            <monounsaturated_fat>2.298</monounsaturated_fat>
            <trans_fat>0</trans_fat>
            <cholesterol>90</cholesterol>
            <sodium>320</sodium>
            <potassium>80</potassium>
            <fiber>0.8</fiber>
            <sugar>4.87</sugar>
            <added_sugars>10</added_sugars>
            <vitamin_d>2</vitamin_d>
            <vitamin_a>0</vitamin_a>
            <vitamin_c>0</vitamin_c>
            <calcium>8</calcium>
            <iron>9</iron>
        </serving>
</servings>
</food>

Example Return JSON

{ "food": {"food_id": "4384", "food_name": "Plain French Toast", "food_type": "Generic", "food_url": "http:\/\/www.fatsecret.com\/calories-nutrition\/generic\/french-toast-plain", "servings": {"serving": {"added_sugars": "10", "calcium": "8", "calories": "159", "carbohydrate": "20.02", "cholesterol": "90", "fat": "6.13", "fiber": "0.8", "iron": "9", "measurement_description": "regular slice", "metric_serving_amount": "65.000", "metric_serving_unit": "g", "monounsaturated_fat": "2.298", "number_of_units": "1.000", "polyunsaturated_fat": "1.578", "potassium": "80", "protein": "5.58", "saturated_fat": "1.585", "serving_description": "regular slice", "serving_id": "16758", "serving_url": "http:\/\/www.fatsecret.com\/calories-nutrition\/generic\/french-toast-plain?portionid=16758&portionamount=1.000", "sodium": "320", "sugar": "4.87", "trans_fat": "0", "vitamin_a": "0", "vitamin_c": "0", "vitamin_d": "2" } } }}

Error Code

Code Description
13 Invalid token: "<detail>"
101 Missing required parameter: "<detail>"
106 Invalid ID: "<detail>"
FatSecret Sites
For Developers

For Professionals

For Everyone

FatSecret Platform API

Support
API

About FatSecret

© 2021 FatSecret. All rights reserved.