Models API

The models module provides data models for the USDA Food Data Central API responses.

Food

class usda_fdc.models.Food(fdc_id, description, data_type, publication_date=None, food_class=None, food_category=None, scientific_name=None, brand_owner=None, brand_name=None, ingredients=None, serving_size=None, serving_size_unit=None, household_serving_fulltext=None, nutrients=<factory>, food_portions=<factory>)[source]

Bases: object

Represents a food item from the FDC database.

Parameters:

  • fdc_id (int) –

  • description (str) –

  • data_type (str) –

  • publication_date (str | None) –

  • food_class (str | None) –

  • food_category (str | None) –

  • scientific_name (str | None) –

  • brand_owner (str | None) –

  • brand_name (str | None) –

  • ingredients (str | None) –

  • serving_size (float | None) –

  • serving_size_unit (str | None) –

  • household_serving_fulltext (str | None) –

  • nutrients (List[Nutrient]) –

  • food_portions (List[FoodPortion]) –

fdc_id: int
description: str
data_type: str
publication_date: str | None = None
food_class: str | None = None
food_category: str | None = None
scientific_name: str | None = None
brand_owner: str | None = None
brand_name: str | None = None
ingredients: str | None = None
serving_size: float | None = None
serving_size_unit: str | None = None
household_serving_fulltext: str | None = None
nutrients: List[Nutrient]
food_portions: List[FoodPortion]
classmethod from_api_data(data, abridged=False)[source]

Create a Food instance from API data.

Parameters:

  • data (Dict[str, Any]) – The API response data for a food.

  • abridged (bool) – Whether the data is in abridged format.

Returns:

A Food instance.

Return type:

Food

__init__(fdc_id, description, data_type, publication_date=None, food_class=None, food_category=None, scientific_name=None, brand_owner=None, brand_name=None, ingredients=None, serving_size=None, serving_size_unit=None, household_serving_fulltext=None, nutrients=<factory>, food_portions=<factory>)
Parameters:

  • fdc_id (int) –

  • description (str) –

  • data_type (str) –

  • publication_date (str | None) –

  • food_class (str | None) –

  • food_category (str | None) –

  • scientific_name (str | None) –

  • brand_owner (str | None) –

  • brand_name (str | None) –

  • ingredients (str | None) –

  • serving_size (float | None) –

  • serving_size_unit (str | None) –

  • household_serving_fulltext (str | None) –

  • nutrients (List[Nutrient]) –

  • food_portions (List[FoodPortion]) –

Return type:

None

Nutrient

class usda_fdc.models.Nutrient(id, name, amount, unit_name, nutrient_nbr=None, rank=None)[source]

Bases: object

Represents a nutrient in a food item.

Parameters:

  • id (int) –

  • name (str) –

  • amount (float) –

  • unit_name (str) –

  • nutrient_nbr (int | None) –

  • rank (int | None) –

id: int
name: str
amount: float
unit_name: str
nutrient_nbr: int | None = None
rank: int | None = None
__str__()[source]

String representation of the nutrient.

Return type:

str

classmethod from_api_data(data)[source]

Create a Nutrient instance from API data.

Parameters:

data (Dict[str, Any]) – The API response data for a nutrient.

Returns:

A Nutrient instance.

Return type:

Nutrient

__init__(id, name, amount, unit_name, nutrient_nbr=None, rank=None)
Parameters:

  • id (int) –

  • name (str) –

  • amount (float) –

  • unit_name (str) –

  • nutrient_nbr (int | None) –

  • rank (int | None) –

Return type:

None

FoodPortion

class usda_fdc.models.FoodPortion(id, amount, gram_weight, portion_description=None, modifier=None, measure_unit=None)[source]

Bases: object

Represents a food portion.

Parameters:

  • id (int) –

  • amount (float) –

  • gram_weight (float) –

  • portion_description (str | None) –

  • modifier (str | None) –

  • measure_unit (str | None) –

id: int
amount: float
gram_weight: float
portion_description: str | None = None
modifier: str | None = None
measure_unit: str | None = None
__str__()[source]

String representation of the food portion.

Return type:

str

classmethod from_api_data(data)[source]

Create a FoodPortion instance from API data.

Parameters:

data (Dict[str, Any]) – The API response data for a food portion.

Returns:

A FoodPortion instance.

Return type:

FoodPortion

__init__(id, amount, gram_weight, portion_description=None, modifier=None, measure_unit=None)
Parameters:

  • id (int) –

  • amount (float) –

  • gram_weight (float) –

  • portion_description (str | None) –

  • modifier (str | None) –

  • measure_unit (str | None) –

Return type:

None

SearchResult

class usda_fdc.models.SearchResult(foods, total_hits, current_page, total_pages)[source]

Bases: object

Represents search results from the FDC API.

Parameters:
foods: List[SearchResultFood]
total_hits: int
current_page: int
total_pages: int
classmethod from_api_data(data)[source]

Create a SearchResult instance from API data.

Parameters:

data (Dict[str, Any]) – The API response data for search results.

Returns:

A SearchResult instance.

Return type:

SearchResult

__init__(foods, total_hits, current_page, total_pages)
Parameters:
Return type:

None

SearchResultFood

class usda_fdc.models.SearchResultFood(fdc_id, description, data_type, publication_date=None, food_category=None, brand_owner=None, brand_name=None)[source]

Bases: object

Represents a food item in search results.

Parameters:

  • fdc_id (int) –

  • description (str) –

  • data_type (str) –

  • publication_date (str | None) –

  • food_category (str | None) –

  • brand_owner (str | None) –

  • brand_name (str | None) –

fdc_id: int
description: str
data_type: str
publication_date: str | None = None
food_category: str | None = None
brand_owner: str | None = None
brand_name: str | None = None
classmethod from_api_data(data)[source]

Create a SearchResultFood instance from API data.

Parameters:

data (Dict[str, Any]) – The API response data for a search result food.

Returns:

A SearchResultFood instance.

Return type:

SearchResultFood

__init__(fdc_id, description, data_type, publication_date=None, food_category=None, brand_owner=None, brand_name=None)
Parameters:

  • fdc_id (int) –

  • description (str) –

  • data_type (str) –

  • publication_date (str | None) –

  • food_category (str | None) –

  • brand_owner (str | None) –

  • brand_name (str | None) –

Return type:

None