API Documentation

As of v1.0 every endpoint method carries an explicit _vN suffix matching the upstream API version (e.g. foods_search_v5, food_get_v5, recipes_search_v3). The unsuffixed legacy names (foods_search, food_get, …) remain available as deprecated aliases for the v1.x line and emit DeprecationWarning when called. To surface those warnings during development, run Python with:

python -W default::DeprecationWarning:fatsecret

The endpoint methods below are exposed via resource sub-objects on a fatsecret.Fatsecret instance – e.g. fs.foods.search_v5(...) – and are grouped under top-level guide categories matching FatSecret’s official documentation layout (platform.fatsecret.com/docs/guides/). Each guide contains one subsection per OpenAPI tag (sourced from docs/api-spec/openapi.generated.yaml). Client-only helpers (auth handshake, session lifecycle, time conversion) are listed at the bottom under Client utilities.

Foods

Food

Fatsecret.profile_foods.add_favorite_v1()

ProfileFoodsResource.add_favorite_v1( food_id, serving_id=None, number_of_units=None, )[source]

Add a food to a user’s favorite according to the parameters specified.

Parameters:

food_id (int) – Unique food identifier
serving_id (int | None) – Unique serving identifier
number_of_units (float | None) – 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”. Please note that this is only applicable for when food_type is “Generic” whereas for “Brand” the number of units will always be “1”

Return type:

bool

Notes:: food.add_favorite (v1). Premier-only.

Fatsecret.profile_foods.create_v1()

ProfileFoodsResource.create_v1( brand_name, food_name, serving_size, calories, fat, carbohydrate, protein, brand_type=None, serving_amount=None, serving_amount_unit=None, calories_from_fat=None, saturated_fat=None, polyunsaturated_fat=None, monounsaturated_fat=None, trans_fat=None, cholesterol=None, sodium=None, potassium=None, fiber=None, sugar=None, other_carbohydrate=None, vitamin_a=None, vitamin_c=None, calcium=None, iron=None, region=None, language=None, )[source]

Creates a food for the user according to the parameters specified. The result of the call is the new unique identifier of the newly created food.

Parameters:

brand_name (str) – Brand name, only when food_type is “Brand”. E.G.: “Quaker”
food_name (str) – Name of the food, not including the brand name. E.G.: “Instant Oatmeal”
serving_size (str) – Full description of the serving size. E.G.: “1 serving”
calories (float) – Energy content in kcal
fat (float) – Total fat content in grams
carbohydrate (float) – Total carbohydrate content in grams
protein (float) – Protein content in grams
brand_type (str | None) – Either “manufacturer”, “restaurant” or “supermarket” (default value is “manufacturer”)
serving_amount (str | None) – The quantity combined with serving_amount_unit to derive the total standardized quantity of the serving
serving_amount_unit (str | None) – 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 (default value is “g”)
calories_from_fat (float | None) – The energy content in kcal from fat
saturated_fat (float | None) – Saturated fat content in grams (where available)
polyunsaturated_fat (float | None) – Polyunsaturated fat content in grams (where available)
monounsaturated_fat (float | None) – Monounsaturated fat content in grams (where available)
trans_fat (float | None) – Trans fat content in grams (where available)
cholesterol (float | None) – Cholesterol content in milligrams (where available)
sodium (float | None) – Sodium content in milligrams (where available)
potassium (float | None) – Potassium content in milligrams (where available)
fiber (float | None) – Fiber content in grams (where available)
sugar (float | None) – Sugar content in grams (where available)
other_carbohydrate (float | None) – The other carbohydrate content in grams
vitamin_a (float | None) – Percentage of daily recommended Vitamin A, based on a 2000 calorie diet (where available)
vitamin_c (float | None) – Percentage of daily recommended Vitamin C, based on a 2000 calorie diet (where available)
calcium (float | None) – Percentage of daily recommended Calcium, based on a 2000 calorie diet (where available)
iron (float | None) – Percentage of daily recommended Iron, based on a 2000 calorie diet (where available)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

Any

Notes:: food.create (v1). DEPRECATED upstream. Premier-only.

Fatsecret.profile_foods.create_v2()

ProfileFoodsResource.create_v2( brand_name, food_name, serving_size, calories, fat, carbohydrate, protein, brand_type=None, serving_amount=None, serving_amount_unit=None, calories_from_fat=None, saturated_fat=None, polyunsaturated_fat=None, monounsaturated_fat=None, trans_fat=None, cholesterol=None, sodium=None, potassium=None, fiber=None, sugar=None, added_sugars=None, vitamin_d=None, vitamin_a=None, vitamin_c=None, calcium=None, iron=None, region=None, language=None, )[source]

Creates a food for the user according to the parameters specified. The result of the call is the new unique identifier of the newly created food.

Parameters:

brand_name (str) – Brand name, only when food_type is “Brand”. E.G.: “Quaker”
food_name (str) – Name of the food, not including the brand name. E.G.: “Instant Oatmeal”
serving_size (str) – Full description of the serving size. E.G.: “1 serving”
calories (float) – Energy content in kcal
fat (float) – Total fat content in grams
carbohydrate (float) – Total carbohydrate content in grams
protein (float) – Protein content in grams
brand_type (str | None) – Either “manufacturer”, “restaurant” or “supermarket” (default value is “manufacturer”)
serving_amount (str | None) – The quantity combined with serving_amount_unit to derive the total standardized quantity of the serving
serving_amount_unit (str | None) – 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 (default value is “g”)
calories_from_fat (float | None) – The energy content in kcal from fat
saturated_fat (float | None) – Saturated fat content in grams (where available)
polyunsaturated_fat (float | None) – Polyunsaturated fat content in grams (where available)
monounsaturated_fat (float | None) – Monounsaturated fat content in grams (where available)
trans_fat (float | None) – Trans fat content in grams (where available)
cholesterol (float | None) – Cholesterol content in milligrams (where available)
sodium (float | None) – Sodium content in milligrams (where available)
potassium (float | None) – Potassium content in milligrams (where available)
fiber (float | None) – Fiber content in grams (where available)
sugar (float | None) – Sugar content in grams (where available)
added_sugars (float | None) – Added Sugars content in grams (where available)
vitamin_d (float | None) – Vitamin D content in micrograms (where available)
vitamin_a (float | None) – Vitamin A content in micrograms (where available)
vitamin_c (float | None) – Vitamin C content in milligrams (where available)
calcium (float | None) – Calcium content in milligrams (where available)
iron (float | None) – Iron content in milligrams (where available)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

Any

Notes:: food.create (v2). Premier-only.

Fatsecret.profile_foods.delete_favorite_v1()

ProfileFoodsResource.delete_favorite_v1( food_id, serving_id=None, number_of_units=None, )[source]

Deletes the specified food from the user’s favorite.

Parameters:

food_id (int) – Unique food identifier
serving_id (int | None) – Unique serving identifier
number_of_units (float | None) – 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”. Please note that this is only applicable for when food_type is “Generic” whereas for “Brand” the number of units will always be “1”

Return type:

bool

Notes:: food.delete_favorite (v1). Premier-only.

Fatsecret.foods.find_id_for_barcode_v1()

FoodsResource.find_id_for_barcode_v1(barcode, region=None, language=None)[source]

Returns the food_id matching the barcode specified. Barcodes must be specified as GTIN-13 numbers - a 13-digit number filled in with zeros for the spaces to the left. UPC-A, EAN-13 and EAN-8 barcodes may be specified. UPC-E barcodes should be converted to their UPC-A equivalent (and then specified as GTIN-13 numbers). An interactive demonstration of our Barcode API can be accessed here

Parameters:

barcode (str) – 13-digit GTIN-13 formatted sequence of digits representing the barcode to search against
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

Any

Notes:: food.find_id_for_barcode (v1). Premier-only.

Fatsecret.foods.find_id_for_barcode_v2()

FoodsResource.find_id_for_barcode_v2( barcode, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None, )[source]

Returns detailed nutritional information for the specified food matching the barcode specified. Barcodes must be specified as GTIN-13 numbers - a 13-digit number filled in with zeros for the spaces to the left. UPC-A, EAN-13 and EAN-8 barcodes may be specified. UPC-E barcodes should be converted to their UPC-A equivalent (and then specified as GTIN-13 numbers). An interactive demonstration of our Barcode API can be accessed here

Parameters:

barcode (str) – 13-digit GTIN-13 formatted sequence of digits representing the barcode to search against
include_sub_categories (bool | None) – Response will include the names of all sub categories associated with the food
include_food_images (bool | None) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (bool | None) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (bool | None) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Food instance, or None when the response is empty.

Return type:

Food | None

Notes:: food.find_id_for_barcode (v2). Premier-only.

Fatsecret.foods.get_v1()

FoodsResource.get_v1( food_id, include_sub_categories=None, flag_default_serving=None, region=None, language=None, )[source]

Returns detailed nutritional information for the specified food for each available standard serving size. Use this call to display nutrition values for a food to users.

Parameters:

food_id (int) – Unique food identifier
include_sub_categories (bool | None) – Response will include the names of all sub categories associated with the food
flag_default_serving (bool | None) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Food instance, or None when the response is empty.

Return type:

Food | None

Notes:: food.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.foods.get_v2()

FoodsResource.get_v2(food_id, region=None, language=None)[source]

Returns detailed nutritional information for the specified food.

Parameters:: food_id (str) – Fatsecret food identifier
Return type:: Food | None

Fatsecret.foods.get_v3()

FoodsResource.get_v3( food_id, include_sub_categories=None, flag_default_serving=None, region=None, language=None, )[source]

Returns detailed nutritional information for the specified food for each available standard serving size. Use this call to display nutrition values for a food to users.

Parameters:

food_id (int) – Unique food identifier
include_sub_categories (bool | None) – Response will include the names of all sub categories associated with the food
flag_default_serving (bool | None) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Food instance, or None when the response is empty.

Return type:

Food | None

Notes:: food.get (v3). DEPRECATED upstream. Premier-only.

Fatsecret.foods.get_v4()

FoodsResource.get_v4( food_id, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None, )[source]

Returns detailed nutritional information for the specified food for each available standard serving size. Use this call to display nutrition values for a food to users.

Parameters:

food_id (int) – Unique food identifier
include_sub_categories (bool | None) – Response will include the names of all sub categories associated with the food
include_food_images (bool | None) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (bool | None) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (bool | None) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Food instance, or None when the response is empty.

Return type:

Food | None

Notes:: food.get (v4). DEPRECATED upstream. Premier-only.

Fatsecret.foods.get_v5()

FoodsResource.get_v5( food_id, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None, )[source]

Returns detailed nutritional information for the specified food for each available standard serving size. Use this call to display nutrition values for a food to users.

Parameters:

food_id (int) – Unique food identifier
include_sub_categories (bool | None) – Response will include the names of all sub categories associated with the food
include_food_images (bool | None) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (bool | None) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (bool | None) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Food instance, or None when the response is empty.

Return type:

Food | None

Notes:: food.get (v5). Premier-only.

Food Brands

Fatsecret.classification.brands_get_v1()

ClassificationResource.brands_get_v1( starts_with, brand_type=None, region=None, language=None, )[source]

This is a utility method, returning the list of food brands.

Parameters:

starts_with (str) – Food brands that begin with the first letter is returned. The “*” will return all food brands beginning with a numeric character. If this is not specified then the most popular food brands at the time is returned
brand_type (str | None) – Either “manufacturer”, “restaurant” or “supermarket” (default value is “manufacturer”)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: food_brands.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.classification.brands_get_v2()

ClassificationResource.brands_get_v2( starts_with, brand_type=None, region=None, language=None, )[source]

This is a utility method, returning the list of food brands.

Parameters:

starts_with (str) – Food brands that begin with the first letter is returned. The “*” will return all food brands beginning with a numeric character. If this is not specified then the most popular food brands at the time is returned
brand_type (str | None) – Either “manufacturer”, “restaurant” or “supermarket” (default value is “manufacturer”)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: food_brands.get (v2). Premier-only.

Food Categories

Fatsecret.classification.categories_get_v1()

ClassificationResource.categories_get_v1(region=None, language=None)[source]

This is a utility method, returning the full list of all food categories and their associated unique identifiers.

Parameters:

region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: food_categories.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.classification.categories_get_v2()

ClassificationResource.categories_get_v2(region=None, language=None)[source]

This is a utility method, returning the full list of all food categories and their associated unique identifiers.

Parameters:

region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: food_categories.get (v2). Premier-only.

Food Sub-Categories

Fatsecret.classification.sub_categories_get_v1()

ClassificationResource.sub_categories_get_v1( food_category_id, region=None, language=None, )[source]

This is a utility method, returning the full list of all food sub categories for a food category.

Parameters:

food_category_id (int) – Unique identifier of the food category entry
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: food_sub_categories.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.classification.sub_categories_get_v2()

ClassificationResource.sub_categories_get_v2( food_category_id, region=None, language=None, )[source]

This is a utility method, returning the full list of all food sub categories for a food category.

Parameters:

food_category_id (int) – Unique identifier of the food category entry
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: food_sub_categories.get (v2). Premier-only.

Foods (search, autocomplete, favorites)

Fatsecret.foods.autocomplete_v1()

FoodsResource.autocomplete_v1(expression, max_results=None, region=None)[source]

Returns food elements best matching the search expression specified, ordered by their relevancy to the search expression. An interactive demonstration of our Autocomplete API can be accessed here Note: foods.autocomplete only works for the default region / language combination.

Parameters:

expression (str) – Suggestions for the given expression is returned. E.G.: “chic” will return up to four of the best suggestions that contains “chic”
max_results (int | None) – Maximum number of results to return (default value is 4). This number cannot be greater than 10
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: foods.autocomplete (v1). DEPRECATED upstream. Premier-only.

Fatsecret.foods.autocomplete_v2()

FoodsResource.autocomplete_v2(expression, max_results=None, region=None)[source]

Returns food elements best matching the search expression specified, ordered by their relevancy to the search expression. An interactive demonstration of our Autocomplete API can be accessed here

Parameters:

expression (str) – Suggestions for the given expression is returned. E.G.: “chic” will return up to four of the best suggestions that contains “chic”
max_results (int | None) – Maximum number of results to return (default value is 4). This number cannot be greater than 10
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: foods.autocomplete (v2). Premier-only.

Fatsecret.profile_foods.get_favorites_v1()

ProfileFoodsResource.get_favorites_v1()[source]

Returns the favorite foods for the specified user.

Returns:: List of Food instances.
Return type:: list[Food]

Notes:: foods.get_favorites (v1). DEPRECATED upstream. Premier-only.

Fatsecret.profile_foods.get_favorites_v2()

ProfileFoodsResource.get_favorites_v2()[source]

Returns the favorite foods for the specified user.

Returns:: List of Food instances.
Return type:: list[Food]

Notes:: foods.get_favorites (v2). Premier-only.

Fatsecret.profile_foods.get_most_eaten_v1()

ProfileFoodsResource.get_most_eaten_v1(meal=None)[source]

Returns the favorite foods for the specified user.

Parameters:: meal (str | None) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”
Returns:: List of Food instances.
Return type:: list[Food]

Notes:: foods.get_most_eaten (v1). DEPRECATED upstream. Premier-only.

Fatsecret.profile_foods.get_most_eaten_v2()

ProfileFoodsResource.get_most_eaten_v2(meal=None)[source]

Returns the favorite foods for the specified user.

Parameters:: meal (str | None) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”
Returns:: List of Food instances.
Return type:: list[Food]

Notes:: foods.get_most_eaten (v2). Premier-only.

Fatsecret.profile_foods.get_recently_eaten_v1()

ProfileFoodsResource.get_recently_eaten_v1(meal=None)[source]

Returns the favorite foods for the specified user.

Parameters:: meal (str | None) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”
Returns:: List of Food instances.
Return type:: list[Food]

Notes:: foods.get_recently_eaten (v1). DEPRECATED upstream. Premier-only.

Fatsecret.profile_foods.get_recently_eaten_v2()

ProfileFoodsResource.get_recently_eaten_v2(meal=None)[source]

Returns the favorite foods for the specified user.

Parameters:: meal (str | None) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”
Returns:: List of Food instances.
Return type:: list[Food]

Notes:: foods.get_recently_eaten (v2). Premier-only.

Fatsecret.foods.search_v1()

FoodsResource.search_v1( search_expression=None, page_number=None, max_results=None, generic_description=None, region=None, language=None, )[source]

Conducts a search of the food database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. Search results will be refined according to the user’s prior saved food entries. An interactive demonstration of our Food Search API can be accessed here

Parameters:

search_expression (str | None) – Search expression to match on food names
page_number (int | None) – Zero-based offset into the results for the query
max_results (int | None) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
generic_description (str | None) – Either “weight” or “portion”: Weight (default) - the summary description for key nutritional values is displayed by weight (typically 100g); E.G.: “Per 100g”. Portion - the summary description for key nutritional values is displayed using the default portion size; E.G.: “Per 1 Cup” Note that the summary nutrition description for “Brand” food items is always shown using a “portion” based description
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

List of Food instances.

Return type:

list[Food]

Notes:: foods.search (v1). Premier-only.

Fatsecret.foods.search_v2()

FoodsResource.search_v2( search_expression=None, page_number=None, max_results=None, include_sub_categories=None, flag_default_serving=None, region=None, language=None, )[source]

Conducts a search of the food database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users. An interactive demonstration of our Food Search API can be accessed here

Parameters:

search_expression (str | None) – Search expression to match on food names
page_number (int | None) – Zero-based offset into the results for the query
max_results (int | None) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
include_sub_categories (bool | None) – Response will include the names of all sub categories associated with the food
flag_default_serving (bool | None) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

List of Food instances.

Return type:

list[Food]

Notes:: foods.search (v2). DEPRECATED upstream. Premier-only.

Fatsecret.foods.search_v3()

FoodsResource.search_v3( search_expression=None, page_number=None, max_results=None, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None, )[source]

Conducts a search of the food database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users. An interactive demonstration of our Food Search API can be accessed here

Parameters:

search_expression (str | None) – Search expression to match on food names
page_number (int | None) – Zero-based offset into the results for the query
max_results (int | None) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
include_sub_categories (bool | None) – Response will include the names of all sub categories associated with the food
include_food_images (bool | None) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (bool | None) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (bool | None) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

List of Food instances.

Return type:

list[Food]

Notes:: foods.search (v3). DEPRECATED upstream. Premier-only.

Fatsecret.foods.search_v4()

FoodsResource.search_v4( search_expression=None, page_number=None, max_results=None, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None, )[source]

Conducts a search of the food database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users. An interactive demonstration of our Food Search API can be accessed here

Parameters:

search_expression (str | None) – Search expression to match on food names
page_number (int | None) – Zero-based offset into the results for the query
max_results (int | None) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
include_sub_categories (bool | None) – Response will include the names of all sub categories associated with the food
include_food_images (bool | None) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (bool | None) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (bool | None) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

List of Food instances.

Return type:

list[Food]

Notes:: foods.search (v4). DEPRECATED upstream. Premier-only.

Fatsecret.foods.search_v5()

FoodsResource.search_v5( search_expression=None, page_number=None, max_results=None, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, food_type=None, region=None, language=None, )[source]

Conducts a search of the food database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users. An interactive demonstration of our Food Search API can be accessed here

Parameters:

search_expression (str | None) – Search expression to match on food names
page_number (int | None) – Zero-based offset into the results for the query
max_results (int | None) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
include_sub_categories (bool | None) – Response will include the names of all sub categories associated with the food
include_food_images (bool | None) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (bool | None) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (bool | None) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
food_type (str | None) – Restricts search results to a specific type. Valid values are “none”, “generic” or “brand”. Defaults to “none” i.e no filter
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

List of Food instances.

Return type:

list[Food]

Notes:: foods.search (v5). Premier-only.

Diary

Food Diary Entries

Fatsecret.diary.entries_copy_saved_meal_v1()

DiaryResource.entries_copy_saved_meal_v1(saved_meal_id, meal, date=None)[source]

Copies the food entries for a specified saved meal to a specified meal.

Parameters:

saved_meal_id (int) – Unique saved meal identifier
meal (str) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”
date (int | None) – Number of days since January 1, 1970 (default value is the current day)

Return type:

bool

Notes:: food_entries.copy_saved_meal (v1). Premier-only.

Fatsecret.diary.entries_copy_v1()

DiaryResource.entries_copy_v1(from_date, to_date, meal=None)[source]

Copies the food entries for a specified meal from a nominated date to a nominated date.

Parameters:

from_date (int) – Date to copy food entries from expressed in the number of days since January 1, 1970
to_date (int) – Date to copy food entries to expressed in the number of days since January 1, 1970 (default value is the current day)
meal (str | None) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”

Return type:

bool

Notes:: food_entries.copy (v1). Premier-only.

Fatsecret.diary.entries_get_month_v1()

DiaryResource.entries_get_month_v1(date=None)[source]

Returns summary daily nutritional information for a user’s food diary entries for the month specified. Use this call to display nutritional information to users about their food intake for a nominated month. Days with no food diary entries are not included.

Parameters:: date (int | None) – Number of days since January 1, 1970 (default value is the current day)
Returns:: List of Day instances.
Return type:: list[Day]

Notes:: food_entries.get_month (v1). DEPRECATED upstream. Premier-only.

Fatsecret.diary.entries_get_month_v2()

DiaryResource.entries_get_month_v2(date=None)[source]

Returns summary daily nutritional information for a user’s food diary entries for the month specified. Use this call to display nutritional information to users about their food intake for a nominated month. Days with no food diary entries are not included.

Parameters:: date (int | None) – Number of days since January 1, 1970 (default value is the current day)
Returns:: List of Day instances.
Return type:: list[Day]

Notes:: food_entries.get_month (v2). Premier-only.

Fatsecret.diary.entries_get_v1()

DiaryResource.entries_get_v1(food_entry_id=None, date=None)[source]

Returns saved food diary entries for the user according to the filter specified. This method can be used to return all food diary entries recorded on a nominated date or a single food diary entry with a nominated food_entry_id.

Parameters:

date (datetime | date | int | float | None) – Number of days since January 1, 1970 (default value is the current day)
food_entry_id (str | None) – Unique identifier of the food diary entry

Returns:

List of FoodEntry instances.

Notes:: food_entries.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.diary.entries_get_v2()

DiaryResource.entries_get_v2(food_entry_id=None, date=None)[source]

Returns saved food diary entries for the user according to the filter specified. This method can be used to return all food diary entries recorded on a nominated date or a single food diary entry with a nominated food_entry_id.

Parameters:

date (datetime | date | int | float | None) – Number of days since January 1, 1970 (default value is the current day)
food_entry_id (str | None) – Unique identifier of the food diary entry

Returns:

List of FoodEntry instances.

Notes:: food_entries.get (v2). Premier-only.

Food Diary Entry

Fatsecret.diary.entry_create_v1()

DiaryResource.entry_create_v1( food_id, food_entry_name, serving_id, number_of_units, meal, date=None, )[source]

Records a food diary entry for the user according to the parameters specified.

Parameters:

food_id (int) – Unique food identifier
food_entry_name (str) – A description of the food item as entered by the user; typically the name of the food. E.G.: “Instant Oatmeal”
serving_id (int) – Unique serving identifier
number_of_units (float) – 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”. Please note that this is only applicable for when food_type is “Generic” whereas for “Brand” the number of units will always be “1”
meal (str) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”
date (int | None) – Number of days since January 1, 1970 (default value is the current day)

Returns:

List of FoodEntry instances.

Return type:

list[FoodEntry]

Notes:: food_entry.create (v1). Premier-only.

Fatsecret.diary.entry_delete_v1()

DiaryResource.entry_delete_v1(food_entry_id)[source]

Deletes the specified food entry for the user.

Parameters:: food_entry_id (int) – Unique identifier of the food diary entry
Return type:: bool

Notes:: food_entry.delete (v1). Premier-only.

Fatsecret.diary.entry_edit_v1()

DiaryResource.entry_edit_v1( food_entry_id, food_entry_name=None, serving_id=None, number_of_units=None, meal=None, )[source]

Adjusts the recorded values for a food diary entry. Note that the date of the entry may not be adjusted, however one or more of the other remaining properties – food_entry_name, serving_id, number_of_units, or meal may be altered. In order to shift the date for which a food diary entry was recorded the original entry must be deleted and a new entry recorded.

Parameters:

food_entry_id (int) – Unique identifier of the food diary entry
food_entry_name (str | None) – A description of the food item as entered by the user; typically the name of the food. E.G.: “Instant Oatmeal”
serving_id (int | None) – Unique serving identifier
number_of_units (float | None) – 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”. Please note that this is only applicable for when food_type is “Generic” whereas for “Brand” the number of units will always be “1”
meal (str | None) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”

Return type:

bool

Notes:: food_entry.edit (v1). Premier-only.

Exercise Diary Entries

Fatsecret.exercises.entries_commit_day_v1()

ExercisesResource.entries_commit_day_v1(date=None)[source]

Saves the default exercise entries for the user on a nominated date. The API will always return 24 hours worth of exercise entries for a given user on a given date. Users can set up and save standard routines for the activities they do on any given day of the week, known as “template” exercise entries. When the exercise entries are retrieved for a day that has not previously been committed or adjusted by the user a set of 24 hours worth of “template” or default entries will be returned. The exercise_entries.commit_day method takes the current “template” exercise entries and saves them to the exercise diary. Calling this method is in effect an acknowledgement on behalf of a user that they undertook the activities presented in the template.

Parameters:: date (int | None) – Number of days since January 1, 1970 (default value is the current day)
Return type:: bool

Notes:: exercise_entries.commit_day (v1). Premier-only.

Fatsecret.exercises.entries_get_month_v1()

ExercisesResource.entries_get_month_v1(date=None)[source]

Returns the summary estimated daily calories expended for a user’s exercise diary entries for the month specified. Use this call to display total energy expenditure information to users about their exercise and activities for a nominated month. Days with no saved exercise diary entries are not included.

Parameters:: date (int | None) – Number of days since January 1, 1970 (default value is the current day)
Returns:: List of Day instances.
Return type:: list[Day]

Notes:: exercise_entries.get_month (v1). DEPRECATED upstream. Premier-only.

Fatsecret.exercises.entries_get_month_v2()

ExercisesResource.entries_get_month_v2(date=None)[source]

Returns the summary estimated daily calories expended for a user’s exercise diary entries for the month specified. Use this call to display total energy expenditure information to users about their exercise and activities for a nominated month. Days with no saved exercise diary entries are not included.

Parameters:: date (int | None) – Number of days since January 1, 1970 (default value is the current day)
Returns:: List of Day instances.
Return type:: list[Day]

Notes:: exercise_entries.get_month (v2). Premier-only.

Fatsecret.exercises.entries_get_v1()

ExercisesResource.entries_get_v1(date=None)[source]

Returns the daily exercise entries for the user on a nominated date. The API will always return 24 hours worth of exercise entries for a given user on a given date. These entries will either be “template” entries (which a user may override for any given day of the week) or saved exercise entry values. Once a user saves or updates the entries on any given day, all entries for that day are saved. All adjustments to the day involve reducing the time for an existing activity in order to either add or increase the time taken for another activity. The default entries presented for a user for a given day of the week can be overridden using exercise_entries.save_template.

Parameters:: date (int | None) – Number of days since January 1, 1970 (default value is the current day)
Returns:: List of ExerciseEntry instances.
Return type:: list[ExerciseEntry]

Notes:: exercise_entries.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.exercises.entries_get_v2()

ExercisesResource.entries_get_v2(date=None)[source]

Returns the daily exercise entries for the user on a nominated date. The API will always return 24 hours worth of exercise entries for a given user on a given date. These entries will either be “template” entries (which a user may override for any given day of the week) or saved exercise entry values. Once a user saves or updates the entries on any given day, all entries for that day are saved. All adjustments to the day involve reducing the time for an existing activity in order to either add or increase the time taken for another activity. The default entries presented for a user for a given day of the week can be overridden using exercise_entries.save_template.

Parameters:: date (int | None) – Number of days since January 1, 1970 (default value is the current day)
Returns:: List of ExerciseEntry instances.
Return type:: list[ExerciseEntry]

Notes:: exercise_entries.get (v2). Premier-only.

Fatsecret.exercises.entries_save_template_v1()

ExercisesResource.entries_save_template_v1(days, date=None)[source]

Takes the set of exercise entries on a nominated date and saves these entries as “template” entries for nominated days of the week. By default, the template daily exercise entries for all users for all days of the week are: his method is used to take the saved entries on for a nominated date and to copy them for one or more days of the week as the template daily exercise entries. So, for instance, if a user records 1 hour of walking, 8 hours of sleeping and 15 hours of resting for a particular day in their exercise diary, and then saves that date as a template for Saturday and Sunday, these three activities will be presented as the default exercise entries for all future Saturdays and Sundays.

Parameters:

days (int) – The days of the week specified as bits with Sunday being the 1st bit and Saturday being the last and then converted to an Int. For example Tuesday and Thursday would be represented as 00010100 in bits or 20 in Int where Tuesday is the 3rd bit from the right and Thursday being the 5th. Must be between 0 and 128
date (datetime | date | int | float | None) – Number of days since January 1, 1970 (default value is the current day)

Notes:: exercise_entries.save_template (v1). Premier-only.

Exercise Diary Entry

Fatsecret.exercises.entry_edit_v1()

ExercisesResource.entry_edit_v1( shift_to_id, shift_from_id, minutes, date=None, shift_to_name=None, shift_from_name=None, kcal=None, )[source]

Records a change to a user’s exercise diary entry for a nominated date. All changes to an exercise diary involve either increasing the duration of an existing activity or introducing a new activity for a nominated duration. Because there are always 24 hours worth of exercise entries on any given date, the user must nominate the exercise or activity from which the time was taken to balance out the total duration of activities and exercises for the 24 hour period. As such, each change to the exercise entries on a given day is a “shifting” operation where time is moved from one activity to another. An exercise is removed from the day when all of the time allocated to it is shifted to other exercises.

Parameters:

shift_to_id (int) – ID of the exercise type to shift to
shift_from_id (int) – ID of the exercise type to shift from
minutes (int) – Duration in minutes
date (int | None) – Number of days since January 1, 1970 (default value is the current day)
shift_to_name (str | None) – Only required if shift_to_id is 0 (exercise type “Other”). This is the name of the new custom exercise type to shift to
shift_from_name (str | None) – Only required if shift_from_id is 0 (exercise type “Other”). This is the name of the custom exercise type to shift from
kcal (int | None) – Only required if shift_to_id is 0 (exercise type “Other”). This is the total number of kcals burned for this exercise

Return type:

bool

Notes:: exercise_entry.edit (v1). Premier-only.

Exercises

Fatsecret.exercises.list_v1()

ExercisesResource.list_v1(region=None, language=None)[source]

This is a utility method, returning the full list of all supported exercise type names and their associated unique identifiers.

Parameters:

region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

List of Exercise instances.

Return type:

list[Exercise]

Notes:: exercises.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.exercises.list_v2()

ExercisesResource.list_v2(region=None, language=None)[source]

This is a utility method, returning the full list of all supported exercise type names and their associated unique identifiers.

Parameters:

region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

List of Exercise instances.

Return type:

list[Exercise]

Notes:: exercises.get (v2). Premier-only.

Recipes

Recipe

Fatsecret.recipes.add_favorite_v1()

RecipesResource.add_favorite_v1(recipe_id)[source]

Add a recipe to a user’s favorite.

Parameters:: recipe_id (str) – Unique recipe identifier

Notes:: recipe.add_favorite (v1). Premier-only.

Fatsecret.recipes.delete_favorite_v1()

RecipesResource.delete_favorite_v1(recipe_id)[source]

Deletes the specified recipe from the user’s favorite.

Parameters:: recipe_id (str) – Unique recipe identifier

Notes:: recipe.delete_favorite (v1). Premier-only.

Fatsecret.recipes.get_v1()

RecipesResource.get_v1(recipe_id, region=None)[source]

Returns detailed information for the specified recipe for the standard serving.

Parameters:

recipe_id (int) – Unique recipe identifier
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.

Returns:

RecipesRecipe instance, or None when the response is empty.

Return type:

RecipesRecipe | None

Notes:: recipe.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.recipes.get_v2()

RecipesResource.get_v2(recipe_id, region=None)[source]

Returns detailed information for the specified recipe for the standard serving.

Parameters:

recipe_id (int) – Unique recipe identifier
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.

Returns:

RecipesRecipe instance, or None when the response is empty.

Return type:

RecipesRecipe | None

Notes:: recipe.get (v2). Premier-only.

Recipe Types

Fatsecret.recipes.types_get_v1()

RecipesResource.types_get_v1()[source]

This is a utility method, returning the full list of all supported recipe type names.

Returns:: Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).
Return type:: list

Notes:: recipe_types.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.recipes.types_get_v2()

RecipesResource.types_get_v2(region=None, language=None)[source]

This is a utility method, returning the full list of all supported recipe type names.

Parameters:

region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: recipe_types.get (v2). Premier-only.

Recipes

Fatsecret.recipes.get_favorites_v1()

RecipesResource.get_favorites_v1()[source]

Returns the favorite recipes for the specified user.

Returns:: List of RecipesRecipe instances.
Return type:: list[RecipesRecipe]

Notes:: recipes.get_favorites (v1). DEPRECATED upstream. Premier-only.

Fatsecret.recipes.get_favorites_v2()

RecipesResource.get_favorites_v2()[source]

Returns the favorite recipes for the specified user.

Returns:: List of RecipesRecipe instances.
Return type:: list[RecipesRecipe]

Notes:: recipes.get_favorites (v2). Premier-only.

Fatsecret.recipes.search_v1()

RecipesResource.search_v1( search_expression=None, recipe_type=None, page_number=None, max_results=None, )[source]

Conducts a search of the recipe database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. An interactive demonstration of our Recipe Search API can be accessed here

Parameters:

search_expression (str | None) – Search expression to match on food names
recipe_type (str | None) – Recipe type E.G.: “Appetizer”
page_number (int | None) – Zero-based offset into the results for the query
max_results (int | None) – Maximum number of results to return (default value is 20). This number cannot be greater than 50

Returns:

List of RecipesRecipe instances.

Return type:

list[RecipesRecipe]

Notes:: recipes.search (v1). DEPRECATED upstream. Premier-only.

Fatsecret.recipes.search_v2()

RecipesResource.search_v2( search_expression=None, must_have_images=None, calories_from=None, calories_to=None, carb_percentage_from=None, carb_percentage_to=None, protein_percentage_from=None, protein_percentage_to=None, fat_percentage_from=None, fat_percentage_to=None, prep_time_from=None, prep_time_to=None, page_number=None, max_results=None, sort_by=None, region=None, )[source]

Conducts a search of the recipe database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. An interactive demonstration of our Recipe Search API can be accessed here

Parameters:

search_expression (str | None) – Search expression to match on food names
must_have_images (bool | None) – This option will restrict results to recipes with at least one image
calories_from (int | None) – Minimum calories that are contained in the recipe
calories_to (int | None) – Maximum calories that are contained in the recipe
carb_percentage_from (int | None) – Minimum percentage of the calories composed of carbohydrate
carb_percentage_to (int | None) – Maximum percentage of the calories composed of carbohydrate
protein_percentage_from (int | None) – Minimum percentage of the calories composed of protein
protein_percentage_to (int | None) – Maximum percentage of the calories composed of protein
fat_percentage_from (int | None) – Minimum percentage of the calories composed of fat
fat_percentage_to (int | None) – Maximum percentage of the calories composed of fat
prep_time_from (int | None) – Minimum preparation and cook time in minutes required to create the recipe
prep_time_to (int | None) – Maximum preparation and cook time in minutes required to create the recipe
page_number (int | None) – Zero-based offset into the results for the query
max_results (int | None) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
sort_by (str | None) – This option will order results. Valid options include: newest, oldest, caloriesPerServingAscending, caloriesPerServingDescending. When not explicitly set, the ordering will be returned by newest
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.

Returns:

List of RecipesRecipe instances.

Return type:

list[RecipesRecipe]

Notes:: recipes.search (v2). DEPRECATED upstream. Premier-only.

Fatsecret.recipes.search_v3()

RecipesResource.search_v3( search_expression=None, recipe_types=None, recipe_types_matchall=None, must_have_images=None, calories_from=None, calories_to=None, carb_percentage_from=None, carb_percentage_to=None, protein_percentage_from=None, protein_percentage_to=None, fat_percentage_from=None, fat_percentage_to=None, prep_time_from=None, prep_time_to=None, page_number=None, max_results=None, sort_by=None, region=None, )[source]

Conducts a search of the recipe database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. An interactive demonstration of our Recipe Search API can be accessed here

Parameters:

recipe_types (str | None) – This option filters by specified recipe types and should be provided as a comma separated string of recipe type names. The values are provided via the api: Recipe Types Get All
recipe_types_matchall (bool | None) – This option will affect recipe type filters. If true, a recipe must match all provided recipe types, if false (default) then recipes matching any of the supplied types will be returned, The values are provided via the api: Recipe Types Get All
search_expression (str | None) – Search expression to match on food names
must_have_images (bool | None) – This option will restrict results to recipes with at least one image
calories_from (int | None) – Minimum calories that are contained in the recipe
calories_to (int | None) – Maximum calories that are contained in the recipe
carb_percentage_from (int | None) – Minimum percentage of the calories composed of carbohydrate
carb_percentage_to (int | None) – Maximum percentage of the calories composed of carbohydrate
protein_percentage_from (int | None) – Minimum percentage of the calories composed of protein
protein_percentage_to (int | None) – Maximum percentage of the calories composed of protein
fat_percentage_from (int | None) – Minimum percentage of the calories composed of fat
fat_percentage_to (int | None) – Maximum percentage of the calories composed of fat
prep_time_from (int | None) – Minimum preparation and cook time in minutes required to create the recipe
prep_time_to (int | None) – Maximum preparation and cook time in minutes required to create the recipe
page_number (int | None) – Zero-based offset into the results for the query
max_results (int | None) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
sort_by (str | None) – This option will order results. Valid options include: newest, oldest, caloriesPerServingAscending, caloriesPerServingDescending. When not explicitly set, the ordering will be returned by newest
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.

Returns:

List of RecipesRecipe instances.

Return type:

list[RecipesRecipe]

Notes:: recipes.search (v3). Premier-only.

Profile

Fatsecret.profile.create_v1()

ProfileResource.create_v1(user_id)[source]

Creates a new profile and returns the oauth_token and oauth_secret for the new profile. The token and secret returned by this method are persisted indefinitely and may be used in order to provide profile-specific information storage for users including food and exercise diaries and weight tracking. The response is a newly allocated oauth_token and associated oauth_secret which should be stored and re-used to provide ongoing API services on behalf of a user. The results from this call should be saved and subsequently used to provide ongoing storage to users of your site or service. You are obliged to ensure that the values are held securely and to not disclose any oauth_secret values. You should maintain the relationship between your users and the token and secret values you allocate for them. In addition to creating profiles for your own users, you can also use the full 3-legged OAuth provided by fatsecret.com to attain an access token for a profile that is linked to a user account on fatsecret.com. For more information click here.

Parameters:: user_id (str) – You can set your own ID for the newly created profile if you do not wish to store the auth_token and auth_secret
Returns:: Profile instance, or None when the response is empty.
Return type:: Profile | None

Notes:: profile.create (v1). Premier-only.

Fatsecret.profile.get_auth_v1()

ProfileResource.get_auth_v1(user_id=None)[source]

Returns the authentication information for a nominated user. You can also use the full 3-legged OAuth provided by fatsecret.com to attain an access token for a profile that is linked to a user account on fatsecret.com. For more information click here.

Parameters:: user_id (str | None) – You can set your own ID for the newly created profile if you do not wish to store the auth_token and auth_secret
Returns:: Profile instance, or None when the response is empty.
Return type:: Profile | None

Notes:: profile.get_auth (v1). Premier-only.

Fatsecret.profile.get_v1()

ProfileResource.get_v1()[source]

Returns general status information for a nominated user.

Returns:: Profile instance, or None when the response is empty.
Return type:: Profile | None

Notes:: profile.get (v1). Premier-only.

Saved Meals (Premier)

Saved Meal

Fatsecret.meals.create_v1()

MealsResource.create_v1( saved_meal_name, saved_meal_description=None, meals=None, )[source]

Records a saved meal for the user according to the parameters specified. The result of the call is the new unique identifier of the newly created saved meal.

Parameters:

saved_meal_name (str) – New name of the saved meal
saved_meal_description (str | None) – New description of the saved meal
meals (str | None) – Comma separated list of meals the saved meal is suitable for

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

Any

Notes:: saved_meal.create (v1). Premier-only.

Fatsecret.meals.delete_v1()

MealsResource.delete_v1(saved_meal_id)[source]

Deletes the specified saved meal for the user.

Parameters:: saved_meal_id (int) – Unique saved meal identifier
Return type:: bool

Notes:: saved_meal.delete (v1). Premier-only.

Fatsecret.meals.edit_v1()

MealsResource.edit_v1( saved_meal_id, saved_meal_name=None, saved_meal_description=None, meals=None, )[source]

Records a change to a user’s saved meal.

Parameters:

saved_meal_id (int) – Unique saved meal identifier
saved_meal_name (str | None) – New name of the saved meal
saved_meal_description (str | None) – New description of the saved meal
meals (str | None) – Comma separated list of meals the saved meal is suitable for

Return type:

bool

Notes:: saved_meal.edit (v1). Premier-only.

Saved Meal Item

Fatsecret.meals.item_add_v1()

MealsResource.item_add_v1( saved_meal_id, food_id, saved_meal_item_name, serving_id, number_of_units, )[source]

Adds a food to a user’s saved meal according to the parameters specified. The result of the call is the new unique identifier of the newly created saved meal item.

Parameters:

saved_meal_id (int) – Unique saved meal identifier
food_id (int) – Unique food identifier
saved_meal_item_name (str) – New name of the saved meal item
serving_id (int) – Unique serving identifier
number_of_units (float) – 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”. Please note that this is only applicable for when food_type is “Generic” whereas for “Brand” the number of units will always be “1”

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

Any

Notes:: saved_meal_item.add (v1). Premier-only.

Fatsecret.meals.item_delete_v1()

MealsResource.item_delete_v1(saved_meal_item_id)[source]

Deletes the specified saved meal item for the user.

Parameters:: saved_meal_item_id (int) – Unique saved meal item identifier
Return type:: bool

Notes:: saved_meal_item.delete (v1). Premier-only.

Fatsecret.meals.item_edit_v1()

MealsResource.item_edit_v1( saved_meal_item_id, saved_meal_item_name=None, number_of_units=None, )[source]

Records a change to a user’s saved meal item. Note that the serving_id of the saved meal item may not be adjusted, however one or more of the other remaining properties – saved_meal_item_name or number_of_units may be altered. In order to adjust a serving_id for which a saved_meal_item was recorded the original item must be deleted and a new item recorded.

Parameters:

saved_meal_item_id (int) – Unique saved meal item identifier
saved_meal_item_name (str | None) – New name of the saved meal item
number_of_units (float | None) – 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”. Please note that this is only applicable for when food_type is “Generic” whereas for “Brand” the number of units will always be “1”

Return type:

bool

Notes:: saved_meal_item.edit (v1). Premier-only.

Saved Meal Items

Fatsecret.meals.items_get_v1()

MealsResource.items_get_v1(saved_meal_id)[source]

Returns saved meal items for a specified saved meal.

Parameters:: saved_meal_id (int) – Unique saved meal identifier
Returns:: Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).
Return type:: list

Notes:: saved_meal_items.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.meals.items_get_v2()

MealsResource.items_get_v2(saved_meal_id)[source]

Returns saved meal items for a specified saved meal.

Parameters:: saved_meal_id (int) – Unique saved meal identifier
Returns:: Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).
Return type:: list

Notes:: saved_meal_items.get (v2). Premier-only.

Saved Meals

Fatsecret.meals.get_v1()

MealsResource.get_v1(meal=None)[source]

Returns saved meals for the specified user.

Parameters:: meal (str | None) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”
Returns:: Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).
Return type:: list

Notes:: saved_meals.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.meals.get_v2()

MealsResource.get_v2(meal=None)[source]

Returns saved meals for the specified user.

Parameters:: meal (str | None) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”
Returns:: Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).
Return type:: list

Notes:: saved_meals.get (v2). Premier-only.

Weight (Premier)

Weight

Fatsecret.weight.update_v1()

WeightResource.update_v1( current_weight_kg, date=None, weight_type=None, height_type=None, goal_weight_kg=None, current_height_cm=None, comment=None, )[source]

Records a user’s weight for a nominated date. First time weigh-ins require the goal_weight_kg and current_height_cm parameters. Please note as per the API Terms of Use that it is your responsibility to ensure that the information generated by using the API is not be interpreted as a substitute for medical physician consultation, evaluation, or treatment.

Parameters:

current_weight_kg (float) – Current weight of the user in kilograms
date (int | None) – Number of days since January 1, 1970 (default value is the current day)
weight_type (str | None) – Weight measurement type for this user profile. Valid types are “kg” and “lb” (default value is “kg”)
height_type (str | None) – Height measurement type for this user profile. Valid types are “cm” and “inch” (default value is “cm”)
goal_weight_kg (float | None) – User’s goal weight in kilograms
current_height_cm (float | None) – Current height of the user in centimetres. This is required for the first weigh-in. You can only set this for the first time
comment (str | None) – A comment for this weigh-in

Return type:

bool

Notes:: weight.update (v1). Premier-only.

Weights (history)

Fatsecret.weight.get_month_v1()

WeightResource.get_month_v1(date=None)[source]

Returns the recorded weights for a user for the month specified. Use this call to display a user’s weight chart or log of weight changes for a nominated month. The day elements returned are those where the user entered or updated their weight for the specified month. Days with no recorded weight are not included.

Parameters:: date (int | None) – Number of days since January 1, 1970 (default value is the current day)
Returns:: List of Day instances.
Return type:: list[Day]

Notes:: weights.get_month (v1). DEPRECATED upstream. Premier-only.

Fatsecret.weight.get_month_v2()

WeightResource.get_month_v2(date=None)[source]

Returns the recorded weights for a user for the month specified. Use this call to display a user’s weight chart or log of weight changes for a nominated month. The day elements returned are those where the user entered or updated their weight for the specified month. Days with no recorded weight are not included.

Parameters:: date (int | None) – Number of days since January 1, 1970 (default value is the current day)
Returns:: List of Day instances.
Return type:: list[Day]

Notes:: weights.get_month (v2). Premier-only.

AI (Premier)

Image Recognition

Fatsecret.native.image_recognition_v1()

NativeResource.image_recognition_v1( image_b64, include_food_data=None, eaten_foods=None, region=None, language=None, )[source]

This API detects foods within an image and returns a list of foods from the fatsecret database By passing a list of eaten foods, we will also attempt to determine if any of the inputs match in order to improve the accuracy of the response. NOTE: If an appropriate serving is not found, nutritional information may not be present. This typically occurs when a non-standard serving description is provided for a restaurant-based food. In such scenarios, we recommend using the default serving size returned via the API, indicated by the serving object with “is_default”: true. Additionally, for mobile app interfaces, we recommend not automatically logging all foods and associated serving amounts directly into the user’s food diary. Instead, we recommend displaying an intermittent screen that allows the user to: This approach improves user experience and ensures more accurate food diary entries. NOTE: The entire request body is limited to 1MB characters (1.048M) and as such we recommend to check the request size before hitting the API.

Parameters:

image_b64 (str) – A Base64 image of one or more foods. This field is limited to 999,982 characters
eaten_foods_food_id – The ID of the food that has been previously consumed
eaten_foods_food_name – The name of the food that has been previously consumed
include_food_data (bool | None) – Include full food data in the response (see our food.get API)
eaten_foods (list | None) – An array of previously consumed foods. This may be provided to assist with more accurate matching of foods identified in the input with previously consumed foods
eaten_foods_food_brand – The brand name of the food that has been previously consumed
eaten_foods_serving_description – The serving description of the food that has been previously consumed
eaten_foods_serving_size – The serving size of the food that has been previously consumed
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: image.recognition (v1). Premier-only.

Fatsecret.native.image_recognition_v2()

NativeResource.image_recognition_v2( image_b64, include_food_data=None, eaten_foods=None, region=None, language=None, )[source]

This API identifies food items and their corresponding portion sizes or weights within an image. It returns a list of matched foods from the local, verified fatsecret country database, along with detailed nutritional information for each detected portion. By passing a list of eaten foods, we will also attempt to determine if any of the inputs match in order to improve the accuracy of the response. NOTE: If an appropriate serving is not found, nutritional information may not be present. This typically occurs when a non-standard serving description is provided for a restaurant-based food. In such scenarios, we recommend using the default serving size returned via the API, indicated by the serving object with “is_default”: true. Additionally, for mobile app interfaces, we recommend not automatically logging all foods and associated serving amounts directly into the user’s food diary. Instead, we recommend displaying an intermittent screen that allows the user to: This approach improves user experience and ensures more accurate food diary entries. We support jpg, png and webp formats, with a size of up to 1.09MB. We recommend resizing images to a resolution of either 256x256 or 512x512 pixels.

Parameters:

image_b64 (str) – A Base64 image of one or more foods. This field is limited to 999,982 characters
eaten_foods_food_id – The ID of the food that has been previously consumed
eaten_foods_food_name – The name of the food that has been previously consumed
include_food_data (bool | None) – Include full food data in the response (see our food.get API)
eaten_foods (list | None) – An array of previously consumed foods. This may be provided to assist with more accurate matching of foods identified in the input with previously consumed foods
eaten_foods_food_brand – The brand name of the food that has been previously consumed
eaten_foods_serving_description – The serving description of the food that has been previously consumed
eaten_foods_serving_size – The serving size of the food that has been previously consumed
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: image.recognition (v2). Premier-only.

Natural Language Processing

Fatsecret.native.natural_language_processing_v1()

NativeResource.natural_language_processing_v1( user_input, include_food_data=None, eaten_foods=None, region=None, language=None, )[source]

This API breaks down natural language and returns a list of foods from the fatsecret database By passing a list of eaten foods, we will also attempt to determine if any of the inputs match in order to improve the accuracy of the response. Example: For breakfast I ate a slice of toast with butter NOTE: If an appropriate serving is not found, nutritional information may not be present. This will typically occur for a non-standard serving description provided for a restaurant based food. NOTE: The request body may not exceed 1MB in size. This is inclusive of all body parameters.

Parameters:

user_input (str) – A description of what a user has eaten. May contain multiple items. e.g. “A toast with ham and cheese, an apple, a banana and a cappuccino”. This field is limited to 1000 characters
eaten_foods_food_id – The ID of the food that has been previously consumed
eaten_foods_food_name – The name of the food that has been previously consumed
include_food_data (bool | None) – Include full food data in the response (see our food.get API)
eaten_foods (list | None) – An array of previously consumed foods. This may be provided to assist with more accurate matching of foods identified in the input with previously consumed foods
eaten_foods_food_brand – The brand name of the food that has been previously consumed
eaten_foods_serving_description – The serving description of the food that has been previously consumed
eaten_foods_serving_size – The serving size of the food that has been previously consumed
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

list

Notes:: natural.language.processing (v1). Premier-only.

Feedback

Fatsecret.feedback.submit_v1()

FeedbackResource.submit_v1( issue_type_id, external_id, barcode=None, issue_type=None, notes=None, returned_food_id=None, returned_serving_id=None, image_file_extension=None, region=None, language=None, )[source]

This API method enables developers to submit user feedback regarding potentially incorrect or missing food and/or barcode data. It supports a variety of issue types, including potential food or brand naming errors, incorrect nutrition facts, missing serving sizes, and unrecognized barcodes. To facilitate rapid verification, the API returns signed upload URLs, allowing developers to optionally (but ideally) upload up to three user submitted supporting images of the Barcode, Packaging, and Nutrition Facts via subsequent PUT requests. The subsequent PUT requests will be required to use both the provided URL and the “contentTypeHeader” field in the response as a ‘Content-Type’ header to successfully validate with the signed upload URL(s)

Parameters:

barcode (int | None) – A barcode where a food is associated incorrectly. Required when issue_type_id is 1
issue_type_id (int) – The type ID for the request. Valid options are 1 (Wrong Name/Brand), 2 (Wrong Nutrition Info), 3 (Missing Serving Size), 4 (Barcode not found), 99 (Other)
external_id (str) – Custom identifier for external use. E.g an external unique user identifier
issue_type (str | None) – Issue description. This is to be provided when the issue_type_id is 99 (Other)
notes (str | None) – Custom notes regarding the issue
returned_food_food_id – A food ID that is related to the issue (i.e. barcode incorrect food attached). Required when issue_type_id is 1, 2 or 3
returned_food_serving_id – A foods serving ID that is related to the issue (i.e. incorrect nutrient information). Required when issue_type_id is 2 or 3
image_file_extension (str | None) – The image file extension in which the signed uploads will be generated using. Accepts jpg, jpeg, png and tiff. Defaulted to jpg if not provided
region (str | None) – Results will be filtered by region. E.G.: “FR” returns results from France. If not specified this will default to “US” (United States). Click here for full documentation on localization.
language (str | None) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French
returned_food_id (int | None)
returned_serving_id (int | None)

Returns:

Raw FatSecret response shape (no typed model — see docs/migration-v3.rst).

Return type:

dict

Notes:: feedback (v1). Premier-only.

Client utilities

Fatsecret.authenticate(verifier)[source]

Exchange the verifier (PIN or callback code) for permanent access tokens.

Args:: verifier: PIN displayed to user or returned via callback.
Returns:: (access_token, access_secret)

Parameters:: verifier (str | int)
Return type:: Tuple[str, str]

Fatsecret.close()[source]

Close the current HTTP session.

Return type:: None

Fatsecret.fatsecret_authenticate(password, consumer_key, consumer_secret)[source]

Authenticate a user programmatically using credentials and return an authorized Fatsecret instance.

Note: This uses HTML form emulation against FatSecret’s login flow and may break if the website changes. It is provided for convenience and developer testing, not production OAuth flows.

Parameters:

username (str)
password (str)
consumer_key (str)
consumer_secret (str)

Fatsecret.get_authorize_url(callback_url='oob')[source]

Fetch an OAuth1 request token and return the user-facing authorize URL.

Args:

callback_url: Absolute URL to redirect the user to after they authorize,: or "oob" (out-of-band) to receive a verifier PIN.

Returns:

The authorize URL with the freshly minted oauth_token appended.

Parameters:: callback_url (str)
Return type:: str

static Fatsecret.unix_time(dt)[source]

Convert a datetime to number of days since the Epoch (FatSecret style).

Parameters:: dt (datetime)
Return type:: int

static Fatsecret.unix_time_v2(dt)[source]

Convert datetime/date/timestamp into number of days since 1970-01-01.

Parameters:: dt (datetime | date | int | float)
Return type:: int

static Fatsecret.valid_response(response)[source]

Validate a JSON API response and extract its data or raise an error.

Parameters:: response (Response)