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(...) – with one section per FatSecret API category. Each section’s class signature shows the Python class you use (e.g. FoodsResource for the Foods category). Client-only helpers (auth handshake, session lifecycle, time conversion) are listed at the bottom under Client utilities.

Foods¶

class FoodsResource(client)[source]¶

Generated Foods resource plus a small set of hand-tuned overrides.

Hand overrides (Phase 3 follow-up candidates):

get_v2 — legacy method that bypasses _call and goes directly through session.get + valid_response. Not OAS-derivable; retained verbatim from Phase 1.5 with Phase 2 typed-model wrapping.

Parameters:: client (Fatsecret)

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

Food Classification¶

class ClassificationResource(client)¶

Resource methods for the OAS Food Classification tag (generated).

Parameters:: client (Fatsecret)

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.

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.

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.

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.

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.

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.

Recipes¶

class RecipesResource(client)[source]¶

Generated Recipes resource plus dotted-key and legacy-typo overrides.

Hand overrides:

search_v2 / search_v3 — the upstream API expects dotted parameter names (calories.from, carb_percentage.to, etc.) but Python identifiers cannot contain .. Codegen has no way to know about that translation, so we re-emit these two methods with the explicit snake -> dotted mapping.

get_favorites_v1 / get_favorites_v2 / add_favorite_v1 / delete_favorite_v1 — the docs list these under recipes.* (plural) but the actual API expects recipe.* (singular). Generation is driven from the docs, so we patch the method= value.

Parameters:: client (Fatsecret)

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.

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.

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.

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.

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.

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]¶

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 Foods¶

class ProfileFoodsResource(client)¶

Resource methods for the OAS Profile Foods tag (generated).

Parameters:: client (Fatsecret)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Food Diary¶

class DiaryResource(client)[source]¶

Generated Food Diary resource plus a small set of hand-overrides.

Hand overrides:

entries_get_v1 / entries_get_v2 — short-circuit to [] when neither food_entry_id nor date is supplied. The upstream API would otherwise reject the call; the wrapper has done this guard forever and the test suite asserts it.

Parameters:: client (Fatsecret)

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.

entries_get_v2(food_entry_id=None, date=None)[source]¶

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.

Exercise Diary¶

class ExercisesResource(client)[source]¶

Generated Exercise Diary resource plus a small set of hand-overrides.

Hand overrides:

entries_save_template_v1 — coerce days to int so a string or float input still results in an integer query value, matching the long-standing hand-written behaviour and its passing test suite.

Parameters:: client (Fatsecret)

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.

Weight¶

class WeightResource(client)¶

Resource methods for the OAS Weight Diary tag (generated).

Parameters:: client (Fatsecret)

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.

get_month_v2(date=None)[source]¶

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.

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.

Profile¶

class ProfileResource(client)¶

Resource methods for the OAS Profile Auth tag (generated).

Parameters:: client (Fatsecret)

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.

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.

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¶

class MealsResource(client)¶

Resource methods for the OAS Saved Meals tag (generated).

Parameters:: client (Fatsecret)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

AI¶

class NativeResource(client)[source]¶

Generated Native APIs resource plus body-and-params hand-overrides.

Parameters:: client (Fatsecret)

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.

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_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¶

class FeedbackResource(client)[source]¶

Generated Feedback resource plus body-shape hand-overrides.

Hand overrides:

submit_v1 is overridden to fold returned_food_id and returned_serving_id into a nested returned_food object on the request body, matching the upstream wire format. Codegen has no way to derive this grouping from the flat raw-YAML parameter list.

Parameters:: client (Fatsecret)

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.valid_response(response)[source]¶

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

Parameters:: response (Response)

Models¶

v3 typed response models. Returned by the methods above; access fields via attribute access (food.food_id not food["food_id"]). All inherit from _FS_Base which sets extra="allow" and provides .to_dict() for the v2 dict shape.

Foods¶

pydantic model Food[source]¶

Generated from XSD food.

field food_id: int | None = None¶

field food_name: str | None = None¶

field brand_name: str | None = None¶

field food_type: FoodType | None = None¶

field food_url: str | None = None¶

field food_description: str | None = None¶

field servings: FoodServings | None = None¶

field food_sub_categories: FoodFoodSubCategories | None = None¶

field food_images: FoodFoodImages | None = None¶

field food_attributes: FoodAttributes | None = None¶

pydantic model Foods[source]¶

Generated from XSD foods.

field max_results: int | None = None¶

field total_results: int | None = None¶

field page_number: int | None = None¶

field food: List[Food] | None = None¶

pydantic model FoodsSearch[source]¶

Generated from XSD foods_search.

field max_results: int | None = None¶

field total_results: int | None = None¶

field page_number: int | None = None¶

field results: FoodsSearchResults | None = None¶

pydantic model FoodResults[source]¶

Generated from XSD food_results.

field food: List[Food] | None = None¶

pydantic model FoodSubCategories[source]¶

Generated from XSD food_sub_categories.

field food_sub_category: str | None = None¶

pydantic model FoodAttributes[source]¶

Generated from XSD food_attributes.

field preferences: Preferences | None = None¶

pydantic model FoodImage[source]¶

Generated from XSD food_image.

field image_url: str | None = None¶

field image_type: int | None = None¶

pydantic model FoodImages[source]¶

Generated from XSD food_images.

field food_image: FoodImage | None = None¶

pydantic model Serving[source]¶

Generated from XSD serving.

field serving_id: int | None = None¶

field serving_description: str | None = None¶

field serving_url: str | None = None¶

field metric_serving_amount: Decimal | None = None¶

field metric_serving_unit: str | None = None¶

field number_of_units: Decimal | None = None¶

field measurement_description: str | None = None¶

field is_default: bool | None = None¶

field calories: Decimal | None = None¶

field carbohydrate: Decimal | None = None¶

field protein: Decimal | None = None¶

field fat: Decimal | None = None¶

field saturated_fat: Decimal | None = None¶

field polyunsaturated_fat: Decimal | None = None¶

field monounsaturated_fat: Decimal | None = None¶

field trans_fat: Decimal | None = None¶

field cholesterol: Decimal | None = None¶

field sodium: Decimal | None = None¶

field potassium: Decimal | None = None¶

field fiber: Decimal | None = None¶

field sugar: Decimal | None = None¶

field added_sugars: Decimal | None = None¶

field vitamin_d: Decimal | None = None¶

field vitamin_a: Decimal | None = None¶

field vitamin_c: Decimal | None = None¶

field calcium: Decimal | None = None¶

field iron: Decimal | None = None¶

pydantic model Allergen[source]¶

Generated from XSD allergen.

field id: int | None = None¶

field name: str | None = None¶

field value: Ternary | None = None¶

pydantic model Allergens[source]¶

Generated from XSD allergens.

field allergen: Allergen | None = None¶

pydantic model Preference[source]¶

Generated from XSD preference.

field id: int | None = None¶

field name: str | None = None¶

field value: Ternary | None = None¶

pydantic model Preferences[source]¶

Generated from XSD preferences.

field preference: Preference | None = None¶

Recipes¶

Recipe¶: alias of RecipesRecipe

pydantic model Recipes[source]¶

Generated from XSD recipes.

field max_results: int | None = None¶

field total_results: int | None = None¶

field page_number: int | None = None¶

field recipe: RecipesRecipe | None = None¶

pydantic model RecipesRecipeRecipeIngredients[source]¶

Generated from XSD <inline RecipesRecipeRecipeIngredients>.

field ingredient: List[str] | None = None¶

pydantic model RecipesRecipeRecipeNutrition[source]¶

Generated from XSD <inline RecipesRecipeRecipeNutrition>.

field calories: Decimal | None = None¶

field carbohydrate: Decimal | None = None¶

field protein: Decimal | None = None¶

field fat: Decimal | None = None¶

pydantic model RecipesRecipeRecipeTypes[source]¶

Generated from XSD <inline RecipesRecipeRecipeTypes>.

field recipe_type: List[str] | None = None¶

Diary¶

Food diary entries (per-day / per-month nutrition logs).

pydantic model Day[source]¶

Generated from XSD day.

field date_int: int | None = None¶

field calories: Decimal | None = None¶

field carbohydrate: Decimal | None = None¶

field protein: Decimal | None = None¶

field fat: Decimal | None = None¶

field weight_kg: Decimal | None = None¶

field weight_comment: str | None = None¶

pydantic model Month[source]¶

Generated from XSD month.

field from_date_int: int | None = None¶

field to_date_int: int | None = None¶

field day: List[Day] | None = None¶

pydantic model FoodEntry[source]¶

Generated from XSD food_entry.

field food_entry_id: int | None = None¶

field food_entry_description: str | None = None¶

field date_int: int | None = None¶

field meal: Literal['Breakfast', 'Lunch', 'Dinner', 'Other'] | None = None¶

field food_id: int | None = None¶

field serving_id: int | None = None¶

field number_of_units: Decimal | None = None¶

field food_entry_name: str | None = None¶

field calories: Decimal | None = None¶

field carbohydrate: Decimal | None = None¶

field protein: Decimal | None = None¶

field fat: Decimal | None = None¶

field saturated_fat: Decimal | None = None¶

field polyunsaturated_fat: Decimal | None = None¶

field monounsaturated_fat: Decimal | None = None¶

field trans_fat: Decimal | None = None¶

field cholesterol: Decimal | None = None¶

field sodium: Decimal | None = None¶

field potassium: Decimal | None = None¶

field fiber: Decimal | None = None¶

field sugar: Decimal | None = None¶

field vitamin_a: Decimal | None = None¶

field vitamin_c: Decimal | None = None¶

field calcium: Decimal | None = None¶

field iron: Decimal | None = None¶

pydantic model FoodEntries[source]¶

Generated from XSD food_entries.

field food_entry: List[FoodEntry] | None = None¶

Profile¶

pydantic model Profile[source]¶

Generated from XSD profile.

field auth_token: str | None = None¶

field auth_secret: str | None = None¶

field weight_measure: Literal['Kg', 'Lb'] | None = None¶

field height_measure: Literal['Cm', 'Inch'] | None = None¶

field last_weight_kg: Decimal | None = None¶

field last_weight_date_int: int | None = None¶

field last_weight_comment: str | None = None¶

field goal_weight_kg: Decimal | None = None¶

field height_cm: Decimal | None = None¶

field session_key: str | None = None¶

Exercises¶

pydantic model Exercise[source]¶

Generated from XSD exercise.

field exercise_id: int | None = None¶

field exercise_name: str | None = None¶

pydantic model ExerciseEntry[source]¶

Generated from XSD exercise_entry.

field is_template_value: bool | None = None¶

field exercise_id: int | None = None¶

field exercise_name: str | None = None¶

field minutes: int | None = None¶

field calories: Decimal | None = None¶

pydantic model ExerciseEntries[source]¶

Generated from XSD exercise_entries.

field exercise_entry: List[ExerciseEntry] | None = None¶

pydantic model ExerciseTypes[source]¶

Generated from XSD exercise_types.

field exercise: List[Exercise] | None = None¶

ExerciseDay¶: alias of Day

ExerciseMonth¶: alias of Month

Weight¶

WeightDay¶: alias of Day

WeightMonth¶: alias of Month