pyfatsecret package

Submodules

pyfatsecret.autogen module

pyfatsecret.fatsecret module

class pyfatsecret.fatsecret.Fatsecret(client_id: str, client_secret: str)[source]: Bases: object

pyfatsecret.fatsecret_base module

class pyfatsecret.fatsecret_base.FatsecretBase(**kwargs)[source]

Bases: object

A client for interacting with the Fatsecret API using OAuth 2.0 authentication.

This class handles the initialization of the Fatsecret API client with the provided client credentials, fetching new access tokens, and sending requests to the API with the necessary authorization headers.

API_URL = 'https://platform.fatsecret.com/rest/server.api'

TOKEN_URL = 'https://oauth.fatsecret.com/connect/token'

property access_token

Provides the current access token, refreshing it if it’s close to expiring.

Returns:: The access token.
Return type:: str

property access_token_expires_in: float

Calculates the time in seconds until the current access token expires.

Returns:: The number of seconds until the access token expires.
Return type:: float

get_new_access_token() → dict[source]

Requests a new access token from the FatSecret OAuth 2.0 endpoint using client credentials.

Returns:: A dictionary containing the access token and other data.
Return type:: dict

get_params(**kwargs)[source]

make_request(method: str, params: dict = None) → dict[source]

Makes a request to the FatSecret API using the obtained access token.

Parameters:

method (str) – The API method to call.
params (dict, optional) – Additional parameters for the API request.

Returns:

The JSON response from the API.

Return type:

dict

pyfatsecret.foods module

Module ‘foods.py’ contains the following methods:

and was generated on 21.11.2025 17:09.

class pyfatsecret.foods.Foods(**kwargs)[source]

Bases: FatsecretBase

food_brands_get(starts_with, brand_type=None, region=None, language=None) → dict[source]

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

Parameters:

starts_with (String) – 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 (String, optional) – Either “manufacturer”, “restaurant” or “supermarket” (default value is “manufacturer”)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v1/food_brands.get

Return type:

dict

food_brands_get_v2(starts_with, brand_type=None, region=None, language=None) → dict[source]

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

Parameters:

starts_with (String) – 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 (String, optional) – Either “manufacturer”, “restaurant” or “supermarket” (default value is “manufacturer”)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v2/food_brands.get

Return type:

dict

food_categories_get(region=None, language=None) → dict[source]

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

Parameters:

region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v1/food_categories.get

Return type:

dict

food_categories_get_v2(region=None, language=None) → dict[source]

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

Parameters:

region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v2/food_categories.get

Return type:

dict

food_find_id_for_barcode(barcode, region=None, language=None) → dict[source]

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

Parameters:

barcode (String) – 13-digit GTIN-13 formatted sequence of digits representing the barcode to search against
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v1/food.find_id_for_barcode

Return type:

dict

food_find_id_for_barcode_v2(barcode, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None) → dict[source]

Returns detailed nutritional information for the specified food matching the barcode specified. Barcodes must be specified as GTIN-13 numbers - a 13-digit number filled in with zeros for the spaces to the left. UPC-A, EAN-13 and EAN-8 barcodes may be specified. UPC-E barcodes should be converted to their UPC-A equivalent (and then specified as GTIN-13 numbers). An interactive demonstration of our Barcode API can be accessed here We are introducing version 2 to return the matched food (and associated nutrional information) of the barcode instead of the food_id. This will return the same response as food.get.v5 with the food_id or return with error code 211.

Parameters:

barcode (String) – 13-digit GTIN-13 formatted sequence of digits representing the barcode to search against
include_sub_categories (Boolean, optional) – Response will include the names of all sub categories associated with the food
include_food_images (Boolean, optional) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (Boolean, optional) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (Boolean, optional) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v2/food.find_id_for_barcode

Return type:

dict

food_get(food_id, include_sub_categories=None, flag_default_serving=None, region=None, language=None) → dict[source]

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

Parameters:

food_id (Long) – Unique food identifier
include_sub_categories (Boolean, optional) – Response will include the names of all sub categories associated with the food
flag_default_serving (Boolean, optional) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v1/food.get

Return type:

dict

food_get_v2(food_id, include_sub_categories=None, flag_default_serving=None, region=None, language=None) → dict[source]

Returns detailed nutritional information for the specified food for each available standard serving size. Use this call to display nutrition values for a food to users. On May 27, 2016 the USA Food and Drug Administration (FDA) published new rules on the new Nutrition Facts label for packaged foods to reflect new scientific information, including the link between diet and chronic diseases such as obesity and heart disease. Manufacturers in the USA with $10 million or more in annual sales were required to switch to the new label by January 1, 2020; manufacturers with less than $10 million in annual food sales have until January 1, 2021 to comply. More information can be found here: Changes to the Nutrition Facts Label Please find more information on how to calculate the %DV for your users: Dietary Supplement Label Database

Parameters:

food_id (Long) – Unique food identifier
include_sub_categories (Boolean, optional) – Response will include the names of all sub categories associated with the food
flag_default_serving (Boolean, optional) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v2/food.get

Return type:

dict

food_get_v3(food_id, include_sub_categories=None, flag_default_serving=None, region=None, language=None) → dict[source]

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

Parameters:

food_id (Long) – Unique food identifier
include_sub_categories (Boolean, optional) – Response will include the names of all sub categories associated with the food
flag_default_serving (Boolean, optional) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v3/food.get

Return type:

dict

food_get_v4(food_id, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None) → dict[source]

Returns detailed nutritional information for the specified food for each available standard serving size. Use this call to display nutrition values for a food to users. Allergens, dietary preferences and images have separate access to our normal premier offerings. Please contact us here for enquiries on access to this data.

Parameters:

food_id (Long) – Unique food identifier
include_sub_categories (Boolean, optional) – Response will include the names of all sub categories associated with the food
include_food_images (Boolean, optional) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (Boolean, optional) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (Boolean, optional) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v4/food.get

Return type:

dict

food_get_v5(food_id, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None) → dict[source]

Returns detailed nutritional information for the specified food for each available standard serving size. Use this call to display nutrition values for a food to users. For foods where food_type is Brand, and where the existing serving includes a serving amount, we now provide additional standardized servings. The additional servings will be either 100 g, 100 ml or 1 oz and 100 g, depending on the existing serving measurement unit, and will always have a serving_id=0 Note: These new derived servings cannot be used to add to a food entry via food_entry.create.

Parameters:

food_id (Long) – Unique food identifier
include_sub_categories (Boolean, optional) – Response will include the names of all sub categories associated with the food
include_food_images (Boolean, optional) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (Boolean, optional) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (Boolean, optional) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v5/food.get

Return type:

dict

food_sub_categories_get(food_category_id, region=None, language=None) → dict[source]

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

Parameters:

food_category_id (Long) – Unique identifier of the food category entry
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v1/food_sub_categories.get

Return type:

dict

food_sub_categories_get_v2(food_category_id, region=None, language=None) → dict[source]

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

Parameters:

food_category_id (Long) – Unique identifier of the food category entry
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v2/food_sub_categories.get

Return type:

dict

foods_autocomplete(expression, max_results=None, region=None) → dict[source]

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

Parameters:

expression (String) – Suggestions for the given expression is returned. E.G.: “chic” will return up to four of the best suggestions that contains “chic”
max_results (Int, optional) – Maximum number of results to return (default value is 4). This number cannot be greater than 10
region (String, optional) – 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:

See https://platform.fatsecret.com/docs/v1/foods.autocomplete

Return type:

dict

foods_autocomplete_v2(expression, max_results=None, region=None) → dict[source]

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

Parameters:

expression (String) – Suggestions for the given expression is returned. E.G.: “chic” will return up to four of the best suggestions that contains “chic”
max_results (Int, optional) – Maximum number of results to return (default value is 4). This number cannot be greater than 10
region (String, optional) – 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:

See https://platform.fatsecret.com/docs/v2/foods.autocomplete

Return type:

dict

foods_search(search_expression=None, page_number=None, max_results=None, generic_description=None, region=None, language=None) → dict[source]

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

Parameters:

search_expression (String, optional) – Search expression to match on food names
page_number (Int, optional) – Zero-based offset into the results for the query
max_results (Int, optional) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
generic_description (String, optional) – Either “weight” or “portion”: Weight (default) - the summary description for key nutritional values is displayed by weight (typically 100g); E.G.: “Per 100g”. Portion - the summary description for key nutritional values is displayed using the default portion size; E.G.: “Per 1 Cup” Note that the summary nutrition description for “Brand” food items is always shown using a “portion” based description
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v1/foods.search

Return type:

dict

foods_search_v2(search_expression=None, page_number=None, max_results=None, include_sub_categories=None, flag_default_serving=None, region=None, language=None) → dict[source]

Conducts a search of the food database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users. An interactive demonstration of our Food Search API can be accessed here We are introducing version 2 to allow the content from the food.get.v3 api to respond directly from a food search. This will negate requirements to issue any subsequent calls to the food.get.v3 api.

Parameters:

search_expression (String, optional) – Search expression to match on food names
page_number (Int, optional) – Zero-based offset into the results for the query
max_results (Int, optional) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
include_sub_categories (Boolean, optional) – Response will include the names of all sub categories associated with the food
flag_default_serving (Boolean, optional) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v2/foods.search

Return type:

dict

foods_search_v3(search_expression=None, page_number=None, max_results=None, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None) → dict[source]

Conducts a search of the food database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users. An interactive demonstration of our Food Search API can be accessed here We are introducing version 3 to correspond to an update for the food.get.v4 which includes images for generic foods and allergen / dietary preference information. Allergens, dietary preferences and images have separate access to our normal premier offerings. Please contact us here for enquiries on access to this data.

Parameters:

search_expression (String, optional) – Search expression to match on food names
page_number (Int, optional) – Zero-based offset into the results for the query
max_results (Int, optional) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
include_sub_categories (Boolean, optional) – Response will include the names of all sub categories associated with the food
include_food_images (Boolean, optional) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (Boolean, optional) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (Boolean, optional) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v3/foods.search

Return type:

dict

foods_search_v4(search_expression=None, page_number=None, max_results=None, include_sub_categories=None, include_food_images=None, include_food_attributes=None, flag_default_serving=None, region=None, language=None) → dict[source]

Conducts a search of the food database using the search expression specified. The results are paginated according to a zero-based “page” offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50. Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users. An interactive demonstration of our Food Search API can be accessed here We are introducing version 4 to correspond to an update for the food.get.v5 which includes additional standardized servings for foods where food_type is Brand, and where the existing serving includes a serving amount. The additional servings will be either 100 g, 100 ml or 1 oz and 100 g, depending on the existing serving measurement unit, and will always have a serving_id=0 Note: These new derived servings cannot be used to add to a food entry via food_entry.create.

Parameters:

search_expression (String, optional) – Search expression to match on food names
page_number (Int, optional) – Zero-based offset into the results for the query
max_results (Int, optional) – Maximum number of results to return (default value is 20). This number cannot be greater than 50
include_sub_categories (Boolean, optional) – Response will include the names of all sub categories associated with the food
include_food_images (Boolean, optional) – Response will include food image in the response. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
include_food_attributes (Boolean, optional) – Response will include food dietary preferences and allergens if available. (Requires separate premier offering, please contact us in order for this feature to be enabled for your account)
flag_default_serving (Boolean, optional) – Either “true” or “false” - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option)
region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v4/foods.search

Return type:

dict

pyfatsecret.profile_auth module

Module ‘profile_auth.py’ contains the following methods:

and was generated on 21.11.2025 17:10.

class pyfatsecret.profile_auth.ProfileAuth(**kwargs)[source]

Bases: FatsecretBase

profile_create(user_id) → dict[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 (String) – 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:: See https://platform.fatsecret.com/docs/v1/profile.create
Return type:: dict

profile_get(user_id=None) → dict[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 (String, optional) – 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:: See https://platform.fatsecret.com/docs/v1/profile.get_auth
Return type:: dict

pyfatsecret.profile_exercise_diary module

Module ‘profile_exercise_diary.py’ contains the following methods:

and was generated on 21.11.2025 17:10.

class pyfatsecret.profile_exercise_diary.ProfileExerciseDiary(**kwargs)[source]

Bases: FatsecretBase

exercise_entries_commit_day(date=None) → dict[source]

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

Parameters:: date (Int, optional) – Number of days since January 1, 1970 (default value is the current day)
Returns:: See https://platform.fatsecret.com/docs/v1/exercise_entries.commit_day
Return type:: dict

exercise_entries_get(date=None) → dict[source]

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

Parameters:: date (Int, optional) – Number of days since January 1, 1970 (default value is the current day)
Returns:: See https://platform.fatsecret.com/docs/v1/exercise_entries.get
Return type:: dict

exercise_entries_get_month(date=None) → dict[source]

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

Parameters:: date (Int, optional) – Number of days since January 1, 1970 (default value is the current day)
Returns:: See https://platform.fatsecret.com/docs/v1/exercise_entries.get_month
Return type:: dict

exercise_entries_get_month_v2(date=None) → dict[source]

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

Parameters:: date (Int, optional) – Number of days since January 1, 1970 (default value is the current day)
Returns:: See https://platform.fatsecret.com/docs/v2/exercise_entries.get_month
Return type:: dict

exercise_entries_get_v2(date=None) → dict[source]

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

Parameters:: date (Int, optional) – Number of days since January 1, 1970 (default value is the current day)
Returns:: See https://platform.fatsecret.com/docs/v2/exercise_entries.get
Return type:: dict

exercise_entries_save_template(days, date=None) → dict[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 (Int, optional) – Number of days since January 1, 1970 (default value is the current day)

Returns:

See https://platform.fatsecret.com/docs/v1/exercise_entries.save_template

Return type:

dict

exercise_entry_edit(shift_to_id, shift_from_id, minutes, date=None, shift_to_name=None, shift_from_name=None, kcal=None) → dict[source]

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

Parameters:

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

Returns:

See https://platform.fatsecret.com/docs/v1/exercise_entry.edit

Return type:

dict

exercises_get(region=None, language=None) → dict[source]

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

Parameters:

region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v1/exercises.get

Return type:

dict

exercises_get_v2(region=None, language=None) → dict[source]

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

Parameters:

region (String, optional) – 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 (String, optional) – (Ignored unless region is also specified) Results will be in the specified language. E.G.: “fr” returns results in French

Returns:

See https://platform.fatsecret.com/docs/v2/exercises.get

Return type:

dict

pyfatsecret.profile_food_diary module

Module ‘profile_food_diary.py’ contains the following methods:

and was generated on 21.11.2025 17:10.

class pyfatsecret.profile_food_diary.ProfileFoodDiary(**kwargs)[source]

Bases: FatsecretBase

food_entries_copy(from_date, to_date, meal=None) → dict[source]

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

Parameters:

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

Returns:

See https://platform.fatsecret.com/docs/v1/food_entries.copy

Return type:

dict

food_entries_copy_saved_meal(saved_meal_id, meal, date=None) → dict[source]

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

Parameters:

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

Returns:

See https://platform.fatsecret.com/docs/v1/food_entries.copy_saved_meal

Return type:

dict

food_entries_get(date, food_entry_id) → dict[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 (Int) – Number of days since January 1, 1970 (default value is the current day)
food_entry_id (Long) – Unique identifier of the food diary entry

Returns:

See https://platform.fatsecret.com/docs/v1/food_entries.get

Return type:

dict

food_entries_get_month(date) → dict[source]

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

Parameters:: date (Int) – Number of days since January 1, 1970 (default value is the current day)
Returns:: See https://platform.fatsecret.com/docs/v1/food_entries.get_month
Return type:: dict

food_entries_get_month_v2(date) → dict[source]

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

Parameters:: date (Int) – Number of days since January 1, 1970 (default value is the current day)
Returns:: See https://platform.fatsecret.com/docs/v2/food_entries.get_month
Return type:: dict

food_entries_get_v2(date, food_entry_id) → dict[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 (Int) – Number of days since January 1, 1970 (default value is the current day)
food_entry_id (Long) – Unique identifier of the food diary entry

Returns:

See https://platform.fatsecret.com/docs/v2/food_entries.get

Return type:

dict

food_entry_create(food_id, food_entry_name, serving_id, number_of_units, meal, date) → dict[source]

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

Parameters:

food_id (Long) – Unique food identifier
food_entry_name (String) – A description of the food item as entered by the user; typically the name of the food. E.G.: “Instant Oatmeal”
serving_id (Long) – Unique serving identifier
number_of_units (Decimal) – Number of units in this standard serving size. For instance, if the serving description is “2 tablespoons” the number of units is “2”, while if the serving size is “1 cup” the number of units is “1”. Please note that this is only applicable for when food_type is “Generic” whereas for “Brand” the number of units will always be “1”
meal (String) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”
date (Int) – Number of days since January 1, 1970 (default value is the current day)

Returns:

See https://platform.fatsecret.com/docs/v1/food_entry.create

Return type:

dict

food_entry_delete(food_entry_id) → dict[source]

Deletes the specified food entry for the user.

Parameters:: food_entry_id (Long) – Unique identifier of the food diary entry
Returns:: See https://platform.fatsecret.com/docs/v1/food_entry.delete
Return type:: dict

food_entry_edit(food_entry_id, food_entry_name=None, serving_id=None, number_of_units=None, meal=None) → dict[source]

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

Parameters:

food_entry_id (Long) – Unique identifier of the food diary entry
food_entry_name (String, optional) – A description of the food item as entered by the user; typically the name of the food. E.G.: “Instant Oatmeal”
serving_id (Long, optional) – Unique serving identifier
number_of_units (Decimal, optional) – Number of units in this standard serving size. For instance, if the serving description is “2 tablespoons” the number of units is “2”, while if the serving size is “1 cup” the number of units is “1”. Please note that this is only applicable for when food_type is “Generic” whereas for “Brand” the number of units will always be “1”
meal (String, optional) – Type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”

Returns:

See https://platform.fatsecret.com/docs/v1/food_entry.edit

Return type:

dict

pyfatsecret.profile_foods module

Module ‘profile_foods.py’ contains the following methods:

and was generated on 21.11.2025 17:09.

class pyfatsecret.profile_foods.ProfileFoods(**kwargs)[source]

Bases: FatsecretBase

food_add_favorite(food_id, serving_id=None, number_of_units=None) → dict[source]

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

Parameters:

food_id (Long) – Unique food identifier
serving_id (Long, optional) – Unique serving identifier
number_of_units (Decimal, optional) – 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:

See https://platform.fatsecret.com/docs/v1/food.add_favorite

Return type:

dict

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

Returns:

See https://platform.fatsecret.com/docs/v1/food.create

Return type:

dict

food_create_v2(brand_type, brand_name, food_name, serving_size, calories, fat, carbohydrate, protein, 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) → dict[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. On May 27, 2016 the USA Food and Drug Administration (FDA) published new rules on the new Nutrition Facts label for packaged foods to reflect new scientific information, including the link between diet and chronic diseases such as obesity and heart disease. Manufacturers in the USA with $10 million or more in annual sales were required to switch to the new label by January 1, 2020; manufacturers with less than $10 million in annual food sales have until January 1, 2021 to comply. More information can be found here: Changes to the Nutrition Facts Label Please find more information on how to calculate the %DV for your users: Dietary Supplement Label Database

Parameters:

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

Returns:

See https://platform.fatsecret.com/docs/v2/food.create

Return type:

dict

food_delete_favorite(food_id, serving_id=None, number_of_units=None) → dict[source]

Deletes the specified food from the user’s favorite.

Parameters:

food_id (Long) – Unique food identifier
serving_id (Long, optional) – Unique serving identifier
number_of_units (Decimal, optional) – 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:

See https://platform.fatsecret.com/docs/v1/food.delete_favorite

Return type:

dict

foods_get_favorites() → dict[source]