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 Python resource class (the actual import path you use). Client-only helpers (auth handshake, session lifecycle, time conversion) are listed at the bottom under Client utilities.

FoodsResource

class FoodsResource(client)

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)

Returns detailed nutritional information for the specified food.

Parameters:

food_id (str) – Fatsecret food identifier

Return type:

Food | None

ClassificationResource

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,

)

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,

)

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)

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)

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,

)

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,

)

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.

RecipesResource

class RecipesResource(client)

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)

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)

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()

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()

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,

)

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,

)

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.

ProfileFoodsResource

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,

)

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,

)

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,

)

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,

)

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()

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()

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)

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)

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)

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)

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.

DiaryResource

class DiaryResource(client)

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)

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)

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.

ExercisesResource

class ExercisesResource(client)

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)

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.

WeightResource

class WeightResource(client)

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

Parameters:

client (Fatsecret)

get_month_v1(date=None)

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)

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.

update_v1(

current_weight_kg,

date=None,

weight_type=None,

height_type=None,

goal_weight_kg=None,

current_height_cm=None,

comment=None,

)

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.

ProfileResource

class ProfileResource(client)

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

Parameters:

client (Fatsecret)

create_v1(user_id)

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)

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()

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.

MealsResource

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,

)

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)

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,

)

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)

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)

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,

)

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)

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,

)

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)

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)

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.

NativeResource

class NativeResource(client)

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,

)

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,

)

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,

)

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.

FeedbackResource

class FeedbackResource(client)

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,

)

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)

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()

Close the current HTTP session.

Return type:

None

Fatsecret.fatsecret_authenticate(password, consumer_key, consumer_secret)

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')

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)

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

Parameters:

dt (datetime)

Return type:

int

static Fatsecret.valid_response(response)

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

Parameters:

response (Response)