Client API

The client module provides the main interface for interacting with the USDA Food Data Central API.

FdcClient

class usda_fdc.client.FdcClient(api_key=None, base_url='https://api.nal.usda.gov/fdc/v1/')[source]

Bases: object

Client for interacting with the USDA Food Data Central API.

Parameters:

api_key (str | None) –
base_url (str) –

api_key

The API key for authenticating with the FDC API.

Type:: str

base_url

The base URL for the FDC API.

Type:: str

session

A session object for making HTTP requests.

Type:: requests.Session

__init__(api_key=None, base_url='https://api.nal.usda.gov/fdc/v1/')[source]

Initialize the FDC client.

Parameters:

api_key (str | None) – The API key for authenticating with the FDC API. If not provided, will look for FDC_API_KEY environment variable.
base_url (str) – The base URL for the FDC API.

Raises:

ValueError – If no API key is provided or found in environment variables.

search(query, data_type=None, page_size=50, page_number=1, sort_by=None, sort_order=None, brand_owner=None)[source]

Search for foods using keywords.

Parameters:

query (str) – One or more search terms.
data_type (List[str] | None) – Filter on specific data types (e.g., [“Branded”, “Foundation”]).
page_size (int) – Maximum number of results to return (1-200).
page_number (int) – Page number to retrieve.
sort_by (str | None) – Field to sort by.
sort_order (str | None) – Sort direction (“asc” or “desc”).
brand_owner (str | None) – Filter by brand owner (Branded Foods only).

Returns:

A SearchResult object containing the search results.

Return type:

SearchResult

get_food(fdc_id, format='full', nutrients=None)[source]

Get detailed information for a specific food by FDC ID.

Parameters:

fdc_id (str | int) – The FDC ID of the food.
format (str) – The format of the response (“full” or “abridged”).
nutrients (List[int] | None) – List of up to 25 nutrient numbers to include.

Returns:

A Food object containing the food data.

Return type:

Food

get_foods(fdc_ids, format='full', nutrients=None)[source]

Get detailed information for multiple foods by FDC ID.

Parameters:

fdc_ids (List[str | int]) – List of FDC IDs (max 20).
format (str) – The format of the response (“full” or “abridged”).
nutrients (List[int] | None) – List of up to 25 nutrient numbers to include.

Returns:

A list of Food objects.

Return type:

List[Food]

get_nutrients(fdc_id)[source]

Get nutrients for a specific food by FDC ID.

Parameters:: fdc_id (str | int) – The FDC ID of the food.
Returns:: A list of Nutrient objects.
Return type:: List[Nutrient]

list_foods(data_type=None, page_size=50, page_number=1, sort_by=None, sort_order=None)[source]

Get a paged list of foods.

Parameters:

data_type (List[str] | None) – Filter on specific data types.
page_size (int) – Maximum number of results to return (1-200).
page_number (int) – Page number to retrieve.
sort_by (str | None) – Field to sort by.
sort_order (str | None) – Sort direction (“asc” or “desc”).

Returns:

A list of Food objects.

Return type:

List[Food]