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

class Fatsecret(consumer_key: str, consumer_secret: str, session_token: Tuple[str, str] | None = None, auth: Literal['oauth1', 'oauth2'] = 'oauth1', scopes: List[str] | None = None)

Core FatSecret API client logic (auth, request handling, utilities).

authenticate(verifier: str | int) → Tuple[str, str]

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)

close() → None

Close the current HTTP session.

exercise_entries_commit_day(date=None)

Saves the default exercise entries for the user on a nominated date.

Deprecated since version 1.0: Use exercise_entries_commit_day_v1(). This alias will be removed in v2.0.

Parameters:

date (datetime.datetime) – Date to save default exercises on (default value is the current day).

exercise_entries_commit_day_v1(date: datetime | date | int | float | None = None) → bool | Any

exercise_entries.commit_day v1.

exercise_entries_get(date=None)

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.

Deprecated since version 1.0: Use exercise_entries_get_v1() for identical behavior or exercise_entries_get_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

date (datetime.datetime) – Day of exercises to retrieve (default value is the current day).

exercise_entries_get_month(date=None)

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.

Deprecated since version 1.0: Use exercise_entries_get_month_v1() for identical behavior or exercise_entries_get_month_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

date (datetime.datetime) – Day within month to retrieve (default value is the current day for the current month).

exercise_entries_get_month_v1(date: datetime | date | int | float | None = None) → list

exercise_entries.get_month v1 (DEPRECATED upstream).

exercise_entries_get_month_v2(date: datetime | date | int | float | None = None) → list

exercise_entries.get_month v2 (current).

exercise_entries_get_v1(date: datetime | date | int | float | None = None) → list

exercise_entries.get v1 (DEPRECATED upstream).

exercise_entries_get_v2(date: datetime | date | int | float | None = None) → list

exercise_entries.get v2 (current).

exercise_entries_save_template(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.

Deprecated since version 1.0: Use exercise_entries_save_template_v1(). Note that v1 fixes the legacy bug that erroneously hit exercise_entries.get_month; the alias now delegates to the corrected method. This alias will be removed in v2.0.

Parameters:

• days (str) – The days of the week specified as bits with Sunday being the 1st bit and Saturday being the last. For example, Tuesday and Thursday would be represented as 00010100 in bits where Tuesday is the 3rd bit from the right and Thursday being the 5th.

• date (datetime.datetime) – Day of exercises to use as the template (default value is the current day).

exercise_entries_save_template_v1(days: int, date: datetime | date | int | float | None = None) → bool | Any

exercise_entries.save_template v1. Fixes the legacy bug that hit exercise_entries.get_month.

exercise_entry_edit(shift_to_id, shift_from_id, minutes, date=None, shift_to_name=None, shift_from_name=None, kcals=None)

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 (str) – The ID of the exercise type to shift to.

• shift_from_id (str) – The ID of the exercise type to shift from.

• minutes (int) – The number of minutes to shift.

• date (datetime.datetime) – Day to edit (default value is the current day).

• shift_to_name (str) – Only required if shift_to_id is 0 (exercise type “Other”). This is the name of the new custom exercise type to shift to.

• shift_from_name (str) – Only required if shift_from_id is 0 (exercise type “Other”). This is the name of the custom exercise type to shift from.

• kcals (int) – Number of calories burned

Deprecated since version 1.0: Use exercise_entry_edit_v1(). This alias will be removed in v2.0.

exercise_entry_edit_v1(shift_to_id: str, shift_from_id: str, minutes: int, date: datetime | date | int | float | None = None, shift_to_name: str | None = None, shift_from_name: str | None = None, kcal: int | None = None) → bool | Any

exercise_entry.edit v1. Shifts time between activities while maintaining 24h balance.

exercises_get()

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

Deprecated since version 1.0: Use exercises_get_v1() for identical behavior or exercises_get_v2() for the current upstream version. This alias will be removed in v2.0.

exercises_get_v1(region: str | None = None, language: str | None = None) → list

exercises.get v1 (DEPRECATED upstream).

exercises_get_v2(region: str | None = None, language: str | None = None) → list

exercises.get v2 (current). Region/language are Premier-exclusive.

fatsecret_authenticate(password: str, consumer_key: str, consumer_secret: str)

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.

feedback_v1(issue_type_id: int, external_id: str, barcode: int | None = None, issue_type: str | None = None, notes: str | None = None, returned_food_id: int | None = None, returned_serving_id: int | None = None, image_file_extension: str | None = None, region: str | None = None, language: str | None = None) → dict

feedback v1. URL-based REST endpoint (POST).

Premier-exclusive. OAuth2 scope: feedback. issue_type_id codes: 1=Wrong Name/Brand, 2=Wrong Nutrition, 3=Missing Serving Size, 4=Barcode not found, 99=Other.

food_add_favorite(food_id, serving_id=None, number_of_units=None)

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

Deprecated since version 1.0: Use food_add_favorite_v1(). This alias will be removed in v2.0.

Parameters:

• food_id (str) – The ID of the favorite food to add.

• serving_id (str) – Only required if number_of_units is present. This is the ID of the favorite serving.

• number_of_units (float) – Only required if serving_id is present. This is the favorite number of servings.

food_add_favorite_v1(food_id: str, serving_id: str | None = None, number_of_units: float | None = None) → bool | Any

food.add_favorite v1.

food_brands_get_v1(starts_with: str, brand_type: str | None = None, region: str | None = None, language: str | None = None) → list

food_brands.get v1 (DEPRECATED upstream). Premier.

food_brands_get_v2(starts_with: str, brand_type: str | None = None, region: str | None = None, language: str | None = None) → list

food_brands.get v2 (current). Premier.

food_categories_get_v1(region: str | None = None, language: str | None = None) → list

food_categories.get v1 (DEPRECATED upstream). Premier.

food_categories_get_v2(region: str | None = None, language: str | None = None) → list

food_categories.get v2 (current). Premier.

food_create_v1(brand_name: str, food_name: str, serving_size: str, calories: float, fat: float, carbohydrate: float, protein: float, brand_type: str | None = None, serving_amount: str | None = None, serving_amount_unit: str | None = None, calories_from_fat: float | None = None, saturated_fat: float | None = None, polyunsaturated_fat: float | None = None, monounsaturated_fat: float | None = None, trans_fat: float | None = None, cholesterol: float | None = None, sodium: float | None = None, potassium: float | None = None, fiber: float | None = None, sugar: float | None = None, other_carbohydrate: float | None = None, vitamin_a: float | None = None, vitamin_c: float | None = None, calcium: float | None = None, iron: float | None = None, region: str | None = None, language: str | None = None) → Any

food.create v1 (DEPRECATED upstream). Premier-exclusive. OAuth1 only.

v1 takes vitamin_a/c, calcium, iron as %DV.

food_create_v2(brand_name: str, food_name: str, serving_size: str, calories: float, fat: float, carbohydrate: float, protein: float, brand_type: str | None = None, serving_amount: str | None = None, serving_amount_unit: str | None = None, calories_from_fat: float | None = None, saturated_fat: float | None = None, polyunsaturated_fat: float | None = None, monounsaturated_fat: float | None = None, trans_fat: float | None = None, cholesterol: float | None = None, sodium: float | None = None, potassium: float | None = None, fiber: float | None = None, sugar: float | None = None, added_sugars: float | None = None, vitamin_d: float | None = None, vitamin_a: float | None = None, vitamin_c: float | None = None, calcium: float | None = None, iron: float | None = None, region: str | None = None, language: str | None = None) → Any

food.create v2 (current). Premier-exclusive. OAuth1 only.

v2 takes raw nutrient values; adds added_sugars and vitamin_d.

food_delete_favorite(food_id, serving_id=None, number_of_units=None)

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

Deprecated since version 1.0: Use food_delete_favorite_v1(). This alias will be removed in v2.0.

Parameters:

• food_id (str) – The ID of the favorite food to add.

• serving_id (str) – Only required if number_of_units is present. This is the ID of the favorite serving.

• number_of_units (float) – Only required if serving_id is present. This is the favorite number of servings.

food_delete_favorite_v1(food_id: str, serving_id: str | None = None, number_of_units: float | None = None) → bool | Any

food.delete_favorite v1.

food_entries_copy(from_date, to_date, meal=None)

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

Deprecated since version 1.0: Use food_entries_copy_v1(). This alias will be removed in v2.0.

Parameters:

• from_date (datetime.datetime) – The date to copy food entries from

• to_date (datetime.datetime) – The date to copy food entries to (default value is the current day).

• meal (str) – The type of meal to copy. Valid meal types are “breakfast”, “lunch”, “dinner” and “other” (default value is all).

food_entries_copy_saved_meal(meal_id, meal, date=None)

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

Deprecated since version 1.0: Use food_entries_copy_saved_meal_v1(). This alias will be removed in v2.0.

Parameters:

• meal_id (str) – The ID of the saved meal

• meal (str) – The type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”.

• date (datetime.datetime) – Day to copy meal to. (default value is the current day).

food_entries_copy_saved_meal_v1(saved_meal_id: str, meal: str, date: datetime | date | int | float | None = None) → bool | Any

food_entries.copy_saved_meal v1.

food_entries_copy_v1(from_date: datetime | date | int | float, to_date: datetime | date | int | float, meal: str | None = None) → bool | Any

food_entries.copy v1.

food_entries_get(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. :: You must specify either date or food_entry_id.

Deprecated since version 1.0: Use food_entries_get_v1() for identical behavior or food_entries_get_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

• food_entry_id (str) – The ID of the food entry to retrieve. You must specify either date or food_entry_id.

• date (datetime.datetmie) – Day to filter food entries by (default value is the current day).

food_entries_get_month(date=None)

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.

Deprecated since version 1.0: Use food_entries_get_month_v1() for identical behavior or food_entries_get_month_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

date (datetime.datetime) – Day in the month to return (default value is the current day to get current month).

food_entries_get_month_v1(date: datetime | date | int | float | None = None) → list

food_entries.get_month v1 (DEPRECATED upstream).

food_entries_get_month_v2(date: datetime | date | int | float | None = None) → list

food_entries.get_month v2 (current).

food_entries_get_v1(food_entry_id: str | None = None, date: datetime | date | int | float | None = None) → list

food_entries.get v1 (DEPRECATED upstream). Pass either food_entry_id or date.

food_entries_get_v2(food_entry_id: str | None = None, date: datetime | date | int | float | None = None) → list

food_entries.get v2 (current). Pass either food_entry_id or date.

food_entry_create(food_id, food_entry_name, serving_id, number_of_units, meal, date=None)

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

Deprecated since version 1.0: Use food_entry_create_v1(). This alias will be removed in v2.0.

Parameters:

• food_id (str) – The ID of the food eaten.

• food_entry_name (str) – The name of the food entry.

• serving_id (str) – The ID of the serving

• number_of_units (float) – The number of servings eaten.

• meal (str) – The type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”.

• date (datetime.datetime) – Day to create food entry on (default value is the current day).

food_entry_create_v1(food_id: str, food_entry_name: str, serving_id: str, number_of_units: float, meal: str, date: datetime | date | int | float | None = None) → list

food_entry.create v1.

food_entry_delete(food_entry_id)

Deletes the specified food entry for the user.

Deprecated since version 1.0: Use food_entry_delete_v1(). This alias will be removed in v2.0.

Parameters:

food_entry_id (str) – The ID of the food entry to delete.

food_entry_delete_v1(food_entry_id: str) → bool | Any

food_entry.delete v1.

food_entry_edit(food_entry_id, entry_name=None, serving_id=None, num_units=None, meal=None)

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.

Deprecated since version 1.0: Use food_entry_edit_v1(). This alias will be removed in v2.0.

Parameters:

• food_entry_id (str) – The ID of the food entry to edit.

• entry_name (str) – The new name of the food entry.

• serving_id (str) – The new ID of the serving to change to.

• num_units (float) – The new number of servings eaten.

• meal (str) – The new type of meal eaten. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”.

food_entry_edit_v1(food_entry_id: str, food_entry_name: str | None = None, serving_id: str | None = None, number_of_units: float | None = None, meal: str | None = None) → bool | Any

food_entry.edit v1.

food_find_id_for_barcode(barcode, region=None, language=None)

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

Deprecated since version 1.0: Use food_find_id_for_barcode_v1() for identical behavior or food_find_id_for_barcode_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

• barcode (str) – The 13-digit GTIN-13 formatted sequence of digits representing the barcode to search against.

• region (str) – Optional region code.

• language (str) – Optional language code.

food_find_id_for_barcode_v1(barcode: str, region: str | None = None, language: str | None = None) → Any

food.find_id_for_barcode v1. Premier (barcode scope). Returns food_id (0 if no match).

food_find_id_for_barcode_v2(barcode: str, include_sub_categories: bool | None = None, include_food_images: bool | None = None, include_food_attributes: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → dict

food.find_id_for_barcode v2. Returns full food record. Premier (barcode scope).

food_get(food_id)

Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users.

Deprecated since version 1.0: Use food_get_v1() for identical behavior or food_get_v5() for the current upstream version. This alias will be removed in v2.0.

Parameters:

food_id (str) – Fatsecret food identifier

food_get_v1(food_id: str, include_sub_categories: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → dict

food.get v1 (DEPRECATED upstream). Vitamins A/C, calcium, iron reported as %DV.

food_get_v2(food_id, region=None, language=None)

Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users.

Parameters:

food_id (str) – Fatsecret food identifier

food_get_v3(food_id: str, include_sub_categories: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → dict

food.get v3 (DEPRECATED upstream). Schema near-identical to v2.

food_get_v4(food_id: str, include_sub_categories: bool | None = None, include_food_images: bool | None = None, include_food_attributes: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → dict

food.get v4 (DEPRECATED upstream). Adds food_images and food_attributes (allergens, preferences).

food_get_v5(food_id: str, include_sub_categories: bool | None = None, include_food_images: bool | None = None, include_food_attributes: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → dict

food.get v5 (current). Brand foods get derived 100g/100ml servings with serving_id=0.

food_sub_categories_get_v1(food_category_id: str, region: str | None = None, language: str | None = None) → list

food_sub_categories.get v1 (DEPRECATED upstream). Premier.

food_sub_categories_get_v2(food_category_id: str, region: str | None = None, language: str | None = None) → list

food_sub_categories.get v2 (current). Premier.

foods_autocomplete(expression, max_results=None, region=None, language=None)

Returns a list of suggestions for the expression specified.

Deprecated since version 1.0: Use foods_autocomplete_v1() for identical behavior or foods_autocomplete_v2() for the current upstream version. Note language is not supported by the underlying endpoint. This alias will be removed in v2.0.

Parameters:

• expression (str) – Suggestions for the given expression is returned. E.G.: “chic” will return up to four of the best suggestions that contains “chic”.

• page_number – page set to return (default 0)

foods_autocomplete_v1(expression: str, max_results: int | None = None, region: str | None = None) → list

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

foods_autocomplete_v2(expression: str, max_results: int | None = None, region: str | None = None) → list

foods.autocomplete v2 (current). Premier-only.

foods_get_favorites()

Returns the favorite foods for the authenticated user.

Deprecated since version 1.0: Use foods_get_favorites_v1() for identical behavior or foods_get_favorites_v2() for the current upstream version. This alias will be removed in v2.0.

foods_get_favorites_v1() → list

foods.get_favorites v1 (DEPRECATED upstream).

foods_get_favorites_v2() → list

foods.get_favorites v2 (current).

foods_get_most_eaten(meal=None)

Returns the most eaten foods for the user according to the meal specified.

Deprecated since version 1.0: Use foods_get_most_eaten_v1() for identical behavior or foods_get_most_eaten_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

meal (str) – ‘breakfast’, ‘lunch’, ‘dinner’, or ‘other’

foods_get_most_eaten_v1(meal: str | None = None) → list

foods.get_most_eaten v1 (DEPRECATED upstream).

foods_get_most_eaten_v2(meal: str | None = None) → list

foods.get_most_eaten v2 (current).

foods_get_recently_eaten(meal=None)

Returns the recently eaten foods for the user according to the meal specified

Deprecated since version 1.0: Use foods_get_recently_eaten_v1() for identical behavior or foods_get_recently_eaten_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

meal (str) – ‘breakfast’, ‘lunch’, ‘dinner’, or ‘other’

foods_get_recently_eaten_v1(meal: str | None = None) → list

foods.get_recently_eaten v1 (DEPRECATED upstream).

foods_get_recently_eaten_v2(meal: str | None = None) → list

foods.get_recently_eaten v2 (current). Premier per spec.

foods_search(search_expression, page_number=None, max_results=None, region=None, language=None)

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.

Deprecated since version 1.0: Use foods_search_v1() for identical behavior or foods_search_v5() for the current upstream version. This alias will be removed in v2.0.

Parameters:

• search_expression (str) – term or phrase to search

• page_number (int) – page set to return (default 0)

• max_results (int) – total results per page (default 20)

foods_search_v1(search_expression: str, page_number: int | None = None, max_results: int | None = None, generic_description: str | None = None, region: str | None = None, language: str | None = None) → list

foods.search v1. Lightweight result set (no nested servings).

Region/language are Premier-exclusive on v1.

foods_search_v2(search_expression: str, page_number: int | None = None, max_results: int | None = None, include_sub_categories: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → list

foods.search v2 (DEPRECATED upstream). Returns nested servings + nutrition. Premier.

foods_search_v3(search_expression: str, page_number: int | None = None, max_results: int | None = None, include_sub_categories: bool | None = None, include_food_images: bool | None = None, include_food_attributes: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → list

foods.search v3 (DEPRECATED upstream). Adds include_food_images and include_food_attributes. Premier.

foods_search_v4(search_expression: str, page_number: int | None = None, max_results: int | None = None, include_sub_categories: bool | None = None, include_food_images: bool | None = None, include_food_attributes: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → list

foods.search v4 (DEPRECATED upstream). Brand foods include derived 100g/100ml servings. Premier.

foods_search_v5(search_expression: str, page_number: int | None = None, max_results: int | None = None, include_sub_categories: bool | None = None, include_food_images: bool | None = None, include_food_attributes: bool | None = None, flag_default_serving: bool | None = None, food_type: str | None = None, region: str | None = None, language: str | None = None) → list

foods.search v5 (current). Adds food_type filter (‘none’/’generic’/’brand’). Premier.

get_authorize_url(callback_url: str = 'oob') → str

New implementation using manual OAuth 1.0 flow to /oauth/request_token on the new endpoint.

Parameters:

callback_url (str) – An absolute URL to redirect the User to when they have completed authentication

image_recognition_v1(image_b64: str, include_food_data: bool | None = None, eaten_foods: list | None = None, region: str | None = None, language: str | None = None) → list

image.recognition v1. URL-based REST endpoint (POST).

Premier-exclusive. OAuth2 scope: image-recognition. image_b64 max ~999,982 chars.

image_recognition_v2(image_b64: str, include_food_data: bool | None = None, eaten_foods: list | None = None, region: str | None = None, language: str | None = None) → list

image.recognition v2. URL-based REST endpoint (POST).

Premier-exclusive. OAuth2 scope: image-recognition. Faster inference, better handling of generic/restaurant/mixed foods.

natural_language_processing_v1(user_input: str, include_food_data: bool | None = None, eaten_foods: list | None = None, region: str | None = None, language: str | None = None) → list

natural.language.processing v1. URL-based REST endpoint (POST).

Premier-exclusive. OAuth2 scope: nlp. user_input limited to 1000 chars.

profile_create(user_id=None)

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.

Deprecated since version 1.0: Use profile_create_v1(). This alias will be removed in v2.0.

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. Particularly useful if you are only using the FatSecret JavaScript API. Use profile.get_auth to retrieve auth_token and auth_secret.

profile_create_v1(user_id: str | None = None) → Any

profile.create v1. Returns (auth_token, auth_secret) when user_id is supplied.

profile_get()

Returns general status information for a nominated user.

Deprecated since version 1.0: Use profile_get_v1(). This alias will be removed in v2.0.

profile_get_auth(user_id)

Returns the authentication information for a nominated user.

Deprecated since version 1.0: Use profile_get_auth_v1(). This alias will be removed in v2.0.

Parameters:

user_id (str) – The user_id specified in profile.create.

profile_get_auth_v1(user_id: str | None = None) → Any

profile.get_auth v1. Returns (auth_token, auth_secret).

profile_get_v1() → dict

profile.get v1. Returns the user’s profile dict.

recipe_add_favorite_v1(recipe_id: str) → bool | Any

recipe.add_favorite v1. Fixes the legacy plural-typo bug (uses singular recipe.add_favorite).

recipe_delete_favorite_v1(recipe_id: str) → bool | Any

recipe.delete_favorite v1. Fixes the legacy plural-typo bug.

recipe_get(recipe_id)

Returns detailed information for the specified recipe.

Deprecated since version 1.0: Use recipe_get_v1() for identical behavior or recipe_get_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

recipe_id (str) – Fatsecret ID of desired recipe

recipe_get_v1(recipe_id: str, region: str | None = None) → dict

recipe.get v1 (DEPRECATED upstream).

recipe_get_v2(recipe_id: str, region: str | None = None) → dict

recipe.get v2 (current). Adds grams_per_portion.

recipe_types_get()

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

Deprecated since version 1.0: Use recipe_types_get_v1() for identical behavior or recipe_types_get_v2() for the current upstream version. This alias will be removed in v2.0.

recipe_types_get_v1() → list

recipe_types.get v1 (DEPRECATED upstream).

recipe_types_get_v2(region: str | None = None, language: str | None = None) → list

recipe_types.get v2 (current). Region/language are Premier-exclusive.

recipes_add_favorite(recipe_id)

Add a recipe to a user’s favorite.

Deprecated since version 1.0: Use recipe_add_favorite_v1() (singular — the upstream method name was misspelled here as a plural). This alias will be removed in v2.0.

Parameters:

recipe_id (str) – The ID of the favorite recipe to add.

recipes_delete_favorite(recipe_id)

Delete a recipe to a user’s favorite.

Deprecated since version 1.0: Use recipe_delete_favorite_v1() (singular — the upstream method name was misspelled here as a plural). This alias will be removed in v2.0.

Parameters:

recipe_id (str) – The ID of the favorite recipe to delete.

recipes_get_favorites()

Returns the favorite recipes for the specified user.

Deprecated since version 1.0: Use recipes_get_favorites_v1() for identical behavior or recipes_get_favorites_v2() for the current upstream version. This alias will be removed in v2.0.

recipes_get_favorites_v1() → list

recipes.get_favorites v1 (DEPRECATED upstream). api_method_param: recipe.get_favorites.

recipes_get_favorites_v2() → list

recipes.get_favorites v2 (current). api_method_param: recipe.get_favorites.v2.

recipes_search(search_expression, recipe_type=None, page_number=None, max_results=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.

Deprecated since version 1.0: Use recipes_search_v1() for identical behavior or recipes_search_v3() for the current upstream version. This alias will be removed in v2.0.

Parameters:

• search_expression (str) – phrase to search on

• recipe_type (str) – type of recipe to filter

• page_number (int) – result page to return (default 0)

• max_results (int) – total results per page to return (default 20)

recipes_search_v1(search_expression: str | None = None, recipe_type: str | None = None, page_number: int | None = None, max_results: int | None = None) → list

recipes.search v1 (DEPRECATED upstream).

recipes_search_v2(search_expression: str | None = None, must_have_images: bool | None = None, calories_from: int | None = None, calories_to: int | None = None, carb_percentage_from: int | None = None, carb_percentage_to: int | None = None, protein_percentage_from: int | None = None, protein_percentage_to: int | None = None, fat_percentage_from: int | None = None, fat_percentage_to: int | None = None, prep_time_from: int | None = None, prep_time_to: int | None = None, page_number: int | None = None, max_results: int | None = None, sort_by: str | None = None, region: str | None = None) → list

recipes.search v2 (DEPRECATED upstream). Adds nutritional/time filters.

recipes_search_v3(search_expression: str | None = None, recipe_types: str | None = None, recipe_types_matchall: bool | None = None, must_have_images: bool | None = None, calories_from: int | None = None, calories_to: int | None = None, carb_percentage_from: int | None = None, carb_percentage_to: int | None = None, protein_percentage_from: int | None = None, protein_percentage_to: int | None = None, fat_percentage_from: int | None = None, fat_percentage_to: int | None = None, prep_time_from: int | None = None, prep_time_to: int | None = None, page_number: int | None = None, max_results: int | None = None, sort_by: str | None = None, region: str | None = None) → list

recipes.search v3 (current). Adds recipe_types comma-list + matchall.

saved_meal_create(meal_name, meal_desc=None, meals=None)

Records a saved meal for the user according to the parameters specified.

Deprecated since version 1.0: Use saved_meal_create_v1(). This alias will be removed in v2.0.

Parameters:

• meal_name (str) – The name of the saved meal.

• meal_desc (str) – A short description of the saved meal.

• meals (list) – A comma separated list of the types of meal this saved meal is suitable for. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”.

saved_meal_create_v1(saved_meal_name: str, saved_meal_description: str | None = None, meals: str | None = None) → Any

saved_meal.create v1.

saved_meal_delete(meal_id)

Deletes the specified saved meal for the user.

Deprecated since version 1.0: Use saved_meal_delete_v1(). This alias will be removed in v2.0.

Parameters:

meal_id (str) – The ID of the saved meal to delete.

saved_meal_delete_v1(saved_meal_id: str) → bool | Any

saved_meal.delete v1.

saved_meal_edit(meal_id, new_name=None, meal_desc=None, meals=None)

Records a change to a user’s saved meal.

Deprecated since version 1.0: Use saved_meal_edit_v1(). This alias will be removed in v2.0.

Parameters:

• meal_id (str) – The ID of the food entry to edit.

• new_name (str) – The new name of the saved meal.

• meal_desc (str) – The new description of the saved meal.

• meals (str) – The new comma separated list of the types of meal this saved meal is suitable for. Valid meal types are “breakfast”, “lunch”, “dinner” and “other”.

saved_meal_edit_v1(saved_meal_id: str, saved_meal_name: str | None = None, saved_meal_description: str | None = None, meals: str | None = None) → bool | Any

saved_meal.edit v1.

saved_meal_get(meal=None)

Returns saved meals for the authenticated user

Deprecated since version 1.0: Use saved_meals_get_v1() (note: plural — the name was corrected) for identical behavior or saved_meals_get_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

meal (str) – Filter result set to ‘Breakfast’, ‘Lunch’, ‘Dinner’, or ‘Other’

saved_meal_item_add(meal_id, food_id, food_entry_name, serving_id, num_units)

Adds a food to a user’s saved meal according to the parameters specified.

Deprecated since version 1.0: Use saved_meal_item_add_v1(). This alias will be removed in v2.0.

Parameters:

• meal_id (str) – The ID of the saved meal.

• food_id (str) – The ID of the food to add to the saved meal.

• food_entry_name (str) – The name of the food to add to the saved meal.

• serving_id (str) – The ID of the serving of the food to add to the saved meal.

• num_units (float) – The number of servings of the food to add to the saved meal.

saved_meal_item_add_v1(saved_meal_id: str, food_id: str, saved_meal_item_name: str, serving_id: str, number_of_units: float) → Any

saved_meal_item.add v1.

saved_meal_item_delete(meal_item_id)

Deletes the specified saved meal item for the user.

Deprecated since version 1.0: Use saved_meal_item_delete_v1(). This alias will be removed in v2.0.

Parameters:

meal_item_id (str) – The ID of the saved meal item to delete.

saved_meal_item_delete_v1(saved_meal_item_id: str) → bool | Any

saved_meal_item.delete v1.

saved_meal_item_edit(meal_item_id, item_name=None, num_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.

Deprecated since version 1.0: Use saved_meal_item_edit_v1(). This alias will be removed in v2.0.

Parameters:

• meal_item_id (str) – The ID of the saved meal item to edit.

• item_name (str) – The new name of the saved meal item.

• num_units (float) – The new number of servings of the saved meal item.

saved_meal_item_edit_v1(saved_meal_item_id: str, saved_meal_item_name: str | None = None, number_of_units: float | None = None) → bool | Any

saved_meal_item.edit v1.

saved_meal_items_get(meal_id)

Returns saved meal items for a specified saved meal.

Deprecated since version 1.0: Use saved_meal_items_get_v1() for identical behavior or saved_meal_items_get_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

meal_id (str) – The ID of the saved meal to retrieve the saved_meal_items for.

saved_meal_items_get_v1(saved_meal_id: str) → list

saved_meal_items.get v1 (DEPRECATED upstream).

saved_meal_items_get_v2(saved_meal_id: str) → list

saved_meal_items.get v2 (current).

saved_meals_get_v1(meal: str | None = None) → list

saved_meals.get v1 (DEPRECATED upstream).

saved_meals_get_v2(meal: str | None = None) → list

saved_meals.get v2 (current).

static unix_time(dt: datetime) → int

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

static unix_time_v2(dt: datetime | date | int | float) → int

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

static valid_response(response: Response)

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

weight_update(current_weight_kg, date=None, weight_type='kg', height_type='cm', 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.

Parameters:

• current_weight_kg (float) – The current weight of the user in kilograms.

• date (datetime.datetime) – Day to for weight record (default value is the current day).

• weight_type (str) – The weight measurement type for this user profile. Valid types are “kg” and “lb”

• height_type (str) – The height measurement type for this user profile. Valid types are “cm” and “inch”

• goal_weight_kg (float) – The goal weight of the user in kilograms. This is required for the first weigh-in.

• current_height_cm (float) – The current height of the user in centimetres. This is required for the first weigh-in. You can only set this for the first time (subsequent updates will not change a user’s height)

• comment (str) – A comment for this weigh-in.

Deprecated since version 1.0: Use weight_update_v1(). This alias will be removed in v2.0.

weight_update_v1(current_weight_kg: float, date: datetime | date | int | float | None = None, weight_type: str | None = None, height_type: str | None = None, goal_weight_kg: float | None = None, current_height_cm: float | None = None, comment: str | None = None) → bool | Any

weight.update v1. First-time entries require goal_weight_kg and current_height_cm.

weights_get_month(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.

Deprecated since version 1.0: Use weights_get_month_v1() for identical behavior or weights_get_month_v2() for the current upstream version. This alias will be removed in v2.0.

Parameters:

date (datetime.datetime) – Day within month to return (default value is the current day for the current month).

weights_get_month_v1(date: datetime | date | int | float | None = None) → list

weights.get_month v1 (DEPRECATED upstream).

weights_get_month_v2(date: datetime | date | int | float | None = None) → list

weights.get_month v2 (current).