FoodData Central Download & API Field Descriptions

Guide to tabs
Download & API Field Descriptions Download & API Field Descriptions (contains 1 line for each fi
Abbreviations List of abbreviations used in the Field Descriptions tab (for exa
Conventions Naming conventions used for naming files and fields (and the
MS Access queries List of sample MS Access queries provided in downloadable M
FNDDS crosswalk Documentation on what FDC fields the FNDDS data were imp
s (contains 1 line for each file and field)
eld Descriptions tab (for example in the synonyms column)
ing files and fields (and their rationale)
provided in downloadable MS Access database
s the FNDDS data were imported into
Download & API Field Descriptions

Table / File Field Definition of data element

These fields appear in multiple files,

and their definition is typically the
GLOBAL column definitions same unless noted below
Unique permanent identifier of a food
fdc_id in the food table

Unique permanent identifier of other

kinds of data (e.g. nutrients, lab
id methods, etc.) in their related table

Non-processed foods obtained directly

from the location where they are
agricultural_acquisition produced

fdc_id ID of the food in the food table

acquisition_date The date this food was obtained

The name of the specific kind of this

market_class food (eg. "Pinto" for pinto beans)

Any special condition relevant to the

production of this food - typically
treatment "drought" or "control"
The state in which this food was
state produced

Acquisitions may be blended with

other acquisitions to create a sample
food, and an acquisition can be used to
created more than one sample food.
This file stores which acquisitions and
acquisition_sample sample foods are related to each other.
ID of the sample food that uses the
fdc_id_of_sample_food acquisitioned food
 ID of the acquisitioned food used in
fdc_id_of_acquisition_food the sample food

Foods whose nutrient values are

typically obtained from food label data
branded_food provided by food brand owners.
fdc_id ID of the food in the food table
brand_owner Brand owner for the food

gtin_upc GTIN or UPC code identifying the food

The list of ingredients (as it appears on
ingredients the product label)
The amount of the serving size when
serving_size expressed as gram or ml
The unit used to express the serving
serving_size_unit size (gram or ml)
amount and unit of serving size when
household_serving_fulltext expressed in household units
The category of the branded food,
branded_food_category assigned by GDSN or Label Insight

The source of the data for this food.

data_source GDSN (for GS1) or LI (for Label Insight).

This date reflects when the product

data was last modified by the data
modified_date provider, i.e., the manufacturer

This is the date when the product

record was available for inclusion in
available_date the database.

Any substance consumed by humans

food for nutrition, taste and/or aroma
Unique permanent identifier of the
fdc_id food
foodClass For internal use only
Type of food data (see Files tab for
data_type possible values).
description Description of the food
 Id of the food category the food
food_category_id belongs to
Date when the food was published to
publication_date FoodData Central

scientific_name The scientific name for the food

A string of characters used to identify
both the current and all historical
food_key records for a specific food.

The value for a generic property of a

food_attribute food

id
ID of the food this food attribute
fdc_id pertains to

The order the attribute will be

seq_num displayed on the released food.

ID of the type of food attribute to

which this value is associated for a
food_attribute_type_id specific food
name Name of food attribute
value The actual value of the attribute

The list of supported attributes

food_attribute_type associated with a food
id

Name of the attribute associated with

the food - should be displayable to
name users
description Description of the attribute

The multiplication factors to be used

when calculating energy from
food_calorie_conversion_factor macronutrients for a specific food
ID of the related row in the
food_nutrient_conversion_factor_id nutrient_conversion_factor table

protein_value The multiplication factor for protein

fat_value The multiplication factor for fat
 The multiplication factor for
carbohydrate_value carbohydrates

food_category Foods of defined similarity

id
code Food group code
description Description of the food group

A constituent part of a food (e.g. bone

food_component is a component of meat)
id
ID of the food this food component
fdc_id pertains to
name The kind of component, e.g. bone

The weight of the component as a

percentage of the total weight of the
pct_weight food
Whether the component is refuse, i.e.
is_refuse not edible

gram_weight The weight of the component in grams

The number of observations on which
data_points the measure is based

Minimum purchase year of all

acquisitions used to derive the
min_year_acquired component value

food_fat_conversion_factor Factor to calculate total lipid fat (204)

Id of the related row in the
food_nutrient_conversion_factor_id nutrient_conversion_factor table

The multiplication factor to convert

fat_nlea_value from fat NLEA (298) to total fat (204)
food_nutrient A nutrient value for a food
id
ID of the food this food nutrient
fdc_id pertains to
ID of the nutrient to which the food
nutrient_id nutrient pertains
 Amount of the nutrient per 100g of
food. Specified in unit defined in the
amount nutrient table.
Number of observations on which the
data_points value is based
ID of the food nutrient derivation
derivation_id technique used to derive the value
standard_error Standard error
min The minimum amount
max The maximum amount
median The median amount

Comments on any unusual aspects of

the food nutrient. Examples might
include why a nutrient value is
footnote different than typically expected.

Minimum purchase year of all

acquisitions used to derive the nutrient
min_year_acquired value
Details of the analysis of the nutrient
nutrient_analysis_details (API only)

Top level type for all types of nutrient

conversion factors. A separate row is
stored for each of these 3 types of
food_nutrient_conversion_factor conversion factor.
id

ID of the food that this food nutrient

fdc_id conversion factor pertains to

Procedure indicating how a food

food_nutrient_derivation nutrient value was obtained
id
Code used for the derivation (e.g. A
code means analytical)
description Description of the derivation
ID of the nutrient source associated
source_id with the derivation
 An information source from which we
food_nutrient_source can obtain food nutrient values
id
Code used for the source (e.g. 4 means
code calculated or imputed)
description Description of the source

food_portion Discrete amount of food

id
ID of the food this food portion
fdc_id pertains to
The order the measure will be
seq_num displayed on the released food.

The number of measure units that

comprise the measure (e.g. if measure
is 3 tsp, the amount is 3). Not defined
for survey (FNDDS) foods (amount is
instead embedded in portion
amount description).

The unit used for the measure (e.g. if

measure is 3 tsp, the unit is tsp). For
food types that do not use measure SR
legacy foods and survey (FNDDS)
foods), a value of '9999' is assigned to
measure_unit_id this field.

Foundation foods: Comments that

provide more specificity on the
measure. For example, for a pizza
measure the dissemination text might
be 1 slice is 1/8th of a 14 inch pizza"."
Survey (FNDDS) foods: The household
portion_description description of the portion.
 Foundation foods: Qualifier of the
measure (e.g. related to food shape or
form) (e.g. melted, crushed, diced).
Survey (FNDDS) foods: The portion
code. SR legacy foods: description of
measures, including the unit of
measure and the measure modifier
modifier (e.g. waffle round (4" dia)).

gram_weight The weight of the measure in grams

The number of observations on which
data_points the measure is based

Comments on any unusual aspects of

the measure. These are released to the
public. Examples might include caveats
on the usage of a measure, or reasons
why a measure gram weight is an
footnote unexpected value.

Minimum purchase year of all

acquisitions used to derive the
min_year_acquired measure value

food_protein_conversion_factor
food_nutrient_conversion_factor_id
value
Id of the related row in the
nutrient_conversion_factor table
The multiplication factor used to
calculate protein from nitrogen

Historical record of an update of food

food_update_log_entry data
fdc_id ID of the food in the food table
description Description of the food
Date when the food was published to
publication_date FoodData Central
 Foods whose nutrient and food
component values are derived
primarily by chemical analysis.
Foundation data also include extensive
underlying metadata, such as the
number of samples, the location and
dates on which samples were
obtained, analytical approaches used,
and if appropriate, cultivar, genotype,
and production practices.

foundation_food
fdc_id ID of the food in the food table

Unique number assigned for the food,

NDB_number different from fdc_id, assigned in SR

Comments on any unusual aspects.

These are released to the public.
Examples might include unusual
footnote aspects of the food overall.

A food that is an ingredient (for survey

(FNDDS) foods) or a source food (for
foundation foods or their source foods)
input_food to another food.
id
fdc_id of the food that contains the
fdc_id input food
fdc_id of the food that is the input
fdc_id_of_input_food food

The order in which to display the input

seq_num food

The amount of the input food included

amount within this food given in terms of unit
 The SR (aka NDB) code of the SR food
that is the ingredient food (used for
sr_code Survey (FNDDS) foods only)

The description of the SR food that is

the ingredient food (used for Survey
sr_description (FNDDS) foods only)

The unit of measure for the amount of

the input food that is included within
this food (used for Survey (FNDDS)
unit foods only)

Code that identifies the portion

description used to measure the
amount of the ingredient (used for
portion_code Survey (FNDDS) foods only)
The description of the portion used to
measure the amount of the ingredient
portion_description (used for Survey (FNDDS) foods only)

gram_weight The weight in grams of the input food

A numeric code identifying processing

on the input food that may have
impacted food nutrient content (used
retention_code for Survey (FNDDS) foods only)

2 = SR description does not match SR

code, other values = internal
survey_flag processing codes for FSRG use only

A chemical procedure used to measure

the amount of one or more nutrients
lab_method in a food
id
description Description of the lab method
General chemical analysis approach
technique used by the lab method

A short, sometimes lab-specific,

sequence of characters used to identify
lab_method_code a lab method
 id

lab_method_id ID of the lab method the code refers to

code Value of the method code

A nutrient whose amount can be

lab_method_nutrient measured by a lab method

id
ID of the lab method the nutrient is
lab_method_id measured by
ID of the nutrient that can be
nutrient_id measured by the lab method

market_acquisition A food obtained for chemical analysis.

fdc_id ID of the food in the food table
brand_description Brand name description of the food
expiration_date Date the food will expire
The weight of the food per the
label_weight product label
The region in which the food was
location purchased, e.g. CA1
acquisition_date Date the food was purchased

The type of establishment in which the

food was acquired (e.g. Retail Store,
sales_type restaurant, farm, etc.)

sample_lot_nbr The lot number of the food

sell_by_date Date the food should be sold by

store_city The city where the food was acquired

The name of the store the food is
store_name purchased from
 store_state The state where the food was acquired
UPC code for the food. Only applicable
upc_code for retail products.

measure_unit units for measuring quantities of foods

id
name name of the unit
abbreviation abbreviated name of the unit

The chemical constituent of a food

(e.g. calcium, vitamin E) officially
recognized as essential to human
nutrient health
id
name Name of the nutrient
The standard unit of measure for the
unit_name nutrient (per 100g of food)
A unique code identifying a nutrient or
nutrient_nbr food constituent

Info for the nutrient source info shown

nutrient_analysis_details
sub_sample_id
amount
lab_method_description
lab_method_technique
on the nutrient source popdown
window. API only.
FDC ID d of the analyzed food
Amount of the nutrient
Lab method used to analyze the
nutrient
The overall technique used by the lab
method

lab_method_link Link to more info about the lab method

nutrient_acquisition_details
nutrient_incoming_name
id
FDC ID, purchase date, and purchase
state
A nutrient name used to identify a
nutrient in incoming nutrient data
 The name used for the incoming
nutrient (e.g. if nutrient is Protein,
name name might be Prot)

The id of the nutrient (in the nutrient

file) related to the incoming name.
Optional (see is_ignored for more
nutrient_id info).

definitions are available from:

www.ars.usda.gov/SP2UserFiles/Place/
12354500/Data/retn/retn06.pdf.
retention_factor

A food that is acquired as a

representative sample of the food
supply. It may be created from a single
acquired food, or from a composite of
sample_food multiple acquired foods.
fdc_id ID of the food in the food table

Foods from the April 2018 release of

the USDA National Nutrient Database
for Standard Reference. Nutrient and
food component values are derived
from chemical analysis and calculation.
sr_legacy_food
fdc_id ID of the food in the food table

Unique number assigned for final food,

starts from the minimum number of
NDB_number 100,000

A portion of a sample food used for the

purpose of specific chemical analysis.
sub_sample_food
fdc_id ID of the food in the food table
ID of the sample food from which the
fdc_id_of_sample_food sub sample originated
 The result of chemical analysis of a lab
on a particular sub sample for a
sub_sample_result particular nutrient
Unique ID for row, same as the
food_nutrient_id food_nutrient ID
adjusted_amount Amount after adjusting for unit
ID of the lab method used to measure
lab_method_id the nutrient
The name of the nutrient as supplied
nutrient_name by the lab

Foods whose consumption is measured

by the What We Eat In America dietary
survey component of the National
Health and Nutrition Examination
Survey (NHANES). Survey nutrient
values are usually calculated from
survey_fndds_food Branded and SR Legacy data.
fdc_id ID of the food in the food table
A unique ID identifying the food within
food_code FNDDS

Unique Identification code for WWEIA

food category to which this food is
wweia_category_code assigned
Start date indicates time period
start_date corresponding to WWEIA data
End date indicates time period
end_date corresponding to WWEIA data

wweia_food_category Food categories for fndds

wweia_food_category_code Unique identification code
wweia_food_category_description Description for a WWEIA Category
Synonyms (used on user interface only)

FDC Source ID
GTIN/UPC

FDC Source ID (used for acquisition foods)

Published, Published Date

More Information (tab), Update Log (tab)

Changes (on Update Log)

Weight (%)

Refuse

Weight (g)

Year Acquired
n

Year Acquired

Deriv. By
Measures (for foundation or legacy foods), Portions
(for survey foods)

Unit

Measure Description
Weight (g)

Year Acquired

Published, Published Date

Sources (for foundation foods), Ingredients (for survey
foods)
Measure

Portion

Weight (g)

Flag
FDC Source ID

Sample Lot Number

Unit
Food Category
API Location

food (is a type of food)

N/A Download only

food (is a type of food)

gtinUpc
foodGroup

food->foodAttributes

N/A

sequenceNumber

foodAttributeType

food->foodAttributes->foodAttributeType

food->nutrientConversionFactors

id
food->foodCategory

food->foodComponents

N/A

percentWeight

food->nutrientConversionFactors

id

food->foodNutrients

N/A

nutrient
foodNutrientDerivation

food->foodNutrients->nutrientAnalysisDetails

N/A - abstract class

N/A

food->foodNutrients->foodNutrientDerivation

foodNutrientSource
food->foodNutrients->foodNutrientDerviation->foodNutrientSource

food->foodPortions

N/A

sequenceNumber

measureUnit
food->nutrientConversionFactors

id

food->foodUpdateLog
food (is a type of food)

ndbNumber

food->inputFoods

N/A

inputFood

sequenceNumber
retentionFactor

For reference only

For reference only

For reference only

food (is a type of food)

sampleLotNumber
food->foodMeasures->measureUnit

food->foodNutrients->nutrient

number

food->foodNutrients->nutrientAnalysisDetails
food->inputFoods->retentionFactor

food (is a type of food)

N/A

food (is a type of food)

ndbNumber

N/A - download only

food->foodNutrients (is a type of food nutrient)

id

food (is a type of food)

wweiaFoodCategory

food->wweiaFoodCategory
Abbreviation Meaning

Abbreviations used in data element names

id unique identification number
max minimum
min minimum

Abbreviations used for API fields

N/A Field is not included as it is a reference to a parent element
Database Data Element Naming
Convention

Lower case

Words separated by underscores

Data type naming conventions

Boolean fields are valued as Y/N

Food relationship definitions

Relationship type
property of a food
subtype of a food
uses a food
Rationale

Not all combinations of DBMS/OS are case sensitive. See

https://stackoverflow.com/questions/16288586/any-reason-to-still-use-snake-case-for-database-
tables-and-columns?rq=1
Spaces are slightly more readable in some contexts, but much less readable in others (e.g. in SQL
queries), camel case requires case sensitivity

Example definition
ID of the food this food attribute pertains to
ID of the food in the food table
ID of the sample food that uses the acquisitioned food
Query Name
q_fndds_<FnddsTableName>
q_foundation_agricultural_acquisition_sources
q_foundation_agricultural_acquisition_nutrients
q_foundation_market_acquisition_sources
q_foundation_market_acquisition_nutrients
q_foundation_market_acquisition_portions
q_foundation_market_acquisition_components
What it retrieves
FNDDS data in the format origininally used to distribute FNDDS 2013-2014
Source agricultural acquisitions of foundation foods
Source agricultural acquisition nutrients of foundation foods
Source market acquisitions of foundation foods
Source market acquisition nutrients of foundation foods
Source market acquisition portions of foundation foods
Source market acquisition components of foundation foods
Notes
FNDDS -> FDC Crosswalk Data was imported from FNDDS 2013-14 MS Access database to FDC Acc
Main goal is to document where imported survey (FNDDS) data is stored in FDC
FNDDS Table Name FNDDS Column Name FDC Table Name*
AddFoodDesc Food code food_attribute
AddFoodDesc Seq num food_attribute
AddFoodDesc Start date survey_fndds_food
AddFoodDesc End date survey_fndds_food
AddFoodDesc Additional food description food_attribute
FNDDSNutVal Food code food_nutrient
FNDDSNutVal Nutrient code food_nutrient
FNDDSNutVal Start date survey_fndds_food
FNDDSNutVal End date survey_fndds_food
FNDDSNutVal Nutrient value food_nutrient
FNDDSRecCount Full File Name
FNDDSRecCount no_of_records
FNDDSSRLinks Food code input_food
FNDDSSRLinks Start date survey_fndds_food
FNDDSSRLinks End date survey_fndds_food
FNDDSSRLinks Seq num input_food
FNDDSSRLinks SR code input_food
FNDDSSRLinks SR description input_food
FNDDSSRLinks Amount input_food
FNDDSSRLinks Measure input_food
FNDDSSRLinks Portion code input_food
FoodPortionDesc Portion description input_food
FNDDSSRLinks Retention code input_food
FNDDSSRLinks Flag input_food
FNDDSSRLinks Weight input_food
FoodPortionDesc Portion code food_portion
FoodPortionDesc Start date survey_fndds_food
FoodPortionDesc End date survey_fndds_food
FoodPortionDesc Portion description food_portion
FoodSubcodeLinks Food code survey_fndds_food
FoodSubcodeLinks Subcode

FoodSubcodeLinks Start date survey_fndds_food

FoodSubcodeLinks End date survey_fndds_food
FoodWeights Food code food_portion
FoodWeights Subcode
FoodWeights Seq num food_portion
FoodWeights Portion code food_portion
FoodWeights Start date survey_fndds_food
FoodWeights End date survey_fndds_food
FoodWeights Portion weight food_portion
MainFoodDesc Food code survey_fndds_food
MainFoodDesc Start date survey_fndds_food
MainFoodDesc End date survey_fndds_food
MainFoodDesc Main food description food
MoistNFatAdjust Food code food_attribute
MoistNFatAdjust Start date survey_fndds_food
MoistNFatAdjust End date survey_fndds_food

MoistNFatAdjust Moisture change food_attribute

MoistNFatAdjust Fat change food_attribute

MoistNFatAdjust Type of fat food_attribute

NutDesc Nutrient code nutrient
NutDesc Nutrient description nutrient
NutDesc Tagname
NutDesc Unit nutrient
NutDesc Decimals
SRNutVal SR code input_food
SRNutVal Nutrient code

SRNutVal Start date survey_fndds_food

SRNutVal End date survey_fndds_food
SRNutVal Nutrient value

SRNutVal Nutrient value change flag

SubcodeDesc Subcode
SubcodeDesc Start date survey_fndds_food
SubcodeDesc End date survey_fndds_food
SubcodeDesc Subcode description
category_list category_number wweia_food_category
category_list category_description wweia_food_category
FNDDS_foodcat food_code survey_fndds_food
FNDDS_foodcat category_number survey_fndds_food
cess database to FDC Access database and CSV files

FDC Column Name* FDC Location on Website

fdc_id Food Details -> FDC ID
seq_num Attributes -> Seq num
start_date Food Details -> Start date
end_date Food Details -> End date
value Attributes -> Additional Description
fdc_id Food Details -> FDC ID
nutrient_id
start_date
end_date Food Details -> End date
amount Nutrients - > Amount

fdc_id Food Details -> FDC ID

start_date Food Details -> Start date
end_date Food Details -> End date
seq_num Ingredients -> Seq Num
sr_code Ingredients -> Code
sr_description Ingredients -> Description
amount Ingredients -> Amount
unit Ingredients -> Measure
portion_code Portions -> Portion Code
portion_description Portions -> Portion Description
retention_code Ingredients -> Retention Code
survey_flag Ingredients -> Flag
gram_weight Ingredients -> Weight(g)
modifier
start_date Food Details -> Start date
end_date Food Details -> End date
portion_description Ingredients -> Portion
food_code Food Details -> Food Code

start_date Food Details -> Start date

end_date Food Details -> End date
fdc_id Food Details -> FDC ID

seq_num Portions -> Seq num

modifier Portions -> Portion code
start_date Food Details -> Start date
end_date Food Details -> End date
gram_weight Portions -> Weight (g)
food_code Food Details -> Food Code
start_date Food Details -> Start date
end_date Food Details -> End date
description Food Details -> Description
fdc_id Food Details -> FDC ID
start_date Food Details -> Start date
end_date Food Details -> End date

value Attributes -> Adjustments

value Attributes -> Adjustments

value Attributes -> Adjustments

nutrient_nbr
name

unit_name

sr_code

start_date Food Details -> Start date

end_date Food Details -> End date

start_date Food Details -> Start date

end_date Food Details -> End date
wweia_category_code
wweia_category_description Food Details -> Food Category
food_code Food Details -> Food Code
wweia_category_code
Migration Notes
Used to link to survey_fndds_food . food_code

Used to link to survey_fndds_food . food_code

Based on nutrient.nutrient_nbr = 'Nutrient code'

Used to link to survey_fndds_food . food_code

Used to link to FoodWeights (We only import subcodes into food_portion

that have a subcode code of 0 ("default gram weights")) so this field is not
needed.

Used to link to survey_fndds_food . food_code

See FoodSubcodeLinks . Subcode explanation
Used to link to survey_fndds_food . food_code

Example, "Moisture change: -20.0%"

Example, "Fat change: 5.3%, Fat code: 4615 (Shortening, vegetable,

household, composite)"
See above

Based on NDB_number
These data were not migrated to FDC. Nutrient values for SR codes used
as the basis for FNDDS 13-14 nutrient values can be found at
https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-
human-nutrition-research-center/food-surveys-research-group/docs/fndds-
download-databases/

These data were not migrated to FDC. Nutrient values for SR codes used
as the basis for FNDDS 13-14 nutrient values can be found at
https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-
human-nutrition-research-center/food-surveys-research-group/docs/fndds-
download-databases/

These data were not migrated to FDC. Nutrient values for SR codes used
as the basis for FNDDS 13-14 nutrient values can be found at
https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-
human-nutrition-research-center/food-surveys-research-group/docs/fndds-
download-databases/

Did not import subCode descriptions other than for subcode=0