API Documentation

class fatsecret.Fatsecret(consumer_key, consumer_secret, session_token=None)[source]

Session for API interaction

Can have an unauthorized session for access to public data or a 3-legged Oauth authenticated session for access to Fatsecret user profile data

Fatsecret only supports OAuth 1.0 with HMAC-SHA1 signed requests.

authenticate(verifier)[source]

Retrieve access tokens once user has approved access to authenticate session

Parameters:verifier (int) – PIN displayed to user or returned by authorize_url when callback url is provided
close()[source]

Session cleanup

exercise_entries_commit_day(date=None)[source]

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

Parameters:date (datetime.datetime) – Date to save default exercises on (default value is the current day).
exercise_entries_get(date=None)[source]

Returns the daily exercise entries for the user on a nominated date.

The API will always return 24 hours worth of exercise entries for a given user on a given date. These entries will either be “template” entries (which a user may override for any given day of the week) or saved exercise entry values.

Parameters:date (datetime.datetime) – Day of exercises to retrieve (default value is the current day).
exercise_entries_get_month(date=None)[source]

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

Parameters:date (datetime.datetime) – Day within month to retrieve (default value is the current day for the current month).
exercise_entries_save_template(days, date=None)[source]

Takes the set of exercise entries on a nominated date and saves these entries as “template” entries for nominated days of the week.

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_entry_edit(shift_to_id, shift_from_id, minutes, date=None, shift_to_name=None, shift_from_name=None, kcals=None)[source]

Records a change to a user’s exercise diary entry for a nominated date.

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

Parameters:
  • shift_to_id (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
exercises_get()[source]

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

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

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

Parameters:
  • food_id (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(food_id, serving_id=None, number_of_units=None)[source]

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

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_entries_copy(from_date, to_date, meal=None)[source]

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

Parameters:
  • from_date (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)[source]

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

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_get(food_entry_id=None, date=None)[source]

Returns saved food diary entries for the user according to the filter specified.

This method can be used to return all food diary entries recorded on a nominated date or a single food diary entry with a nominated food_entry_id.

:: You must specify either date or food_entry_id.

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

Parameters:date (datetime.datetime) – Day in the month to return (default value is the current day to get current month).
food_entry_create(food_id, food_entry_name, serving_id, number_of_units, meal, date=None)[source]

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

Parameters:
  • food_id (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_delete(food_entry_id)[source]

Deletes the specified food entry for the user.

Parameters:food_entry_id (str) – The ID of the food entry to delete.
food_entry_edit(food_entry_id, entry_name=None, serving_id=None, num_units=None, meal=None)[source]

Adjusts the recorded values for a food diary entry.

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

Parameters:
  • food_entry_id (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_get(food_id)[source]

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
foods_get_favorites()[source]

Returns the favorite foods for the authenticated user.

foods_get_most_eaten(meal=None)[source]

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

Parameters:meal (str) – ‘breakfast’, ‘lunch’, ‘dinner’, or ‘other’
foods_get_recently_eaten(meal=None)[source]

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

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

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.

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)
get_authorize_url(callback_url='oob')[source]

URL used to authenticate app to access Fatsecret User data

If no callback url is provided then you’ll need to allow the user to enter in a PIN that Fatsecret displays once access was allowed by the user

Parameters:callback_url (str) – An absolute URL to redirect the User to when they have completed authentication
profile_create(user_id=None)[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.

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_get()[source]

Returns general status information for a nominated user.

profile_get_auth(user_id)[source]

Returns the authentication information for a nominated user.

Parameters:user_id (str) – The user_id specified in profile.create.
recipe_get(recipe_id)[source]

Returns detailed information for the specified recipe.

Parameters:recipe_id (str) – Fatsecret ID of desired recipe
recipe_types_get()[source]

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

recipes_add_favorite(recipe_id)[source]

Add a recipe to a user’s favorite.

Parameters:recipe_id (str) – The ID of the favorite recipe to add.
recipes_delete_favorite(recipe_id)[source]

Delete a recipe to a user’s favorite.

Parameters:recipe_id (str) – The ID of the favorite recipe to delete.
recipes_get_favorites()[source]

Returns the favorite recipes for the specified user.

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.

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)
saved_meal_create(meal_name, meal_desc=None, meals=None)[source]

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

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_delete(meal_id)[source]

Deletes the specified saved meal for the user.

Parameters:meal_id (str) – The ID of the saved meal to delete.
saved_meal_edit(meal_id, new_name=None, meal_desc=None, meals=None)[source]

Records a change to a user’s saved meal.

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_get(meal=None)[source]

Returns saved meals for the authenticated user

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)[source]

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

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_delete(meal_item_id)[source]

Deletes the specified saved meal item for the user.

Parameters:meal_item_id (str) – The ID of the saved meal item to delete.
saved_meal_item_edit(meal_item_id, item_name=None, num_units=None)[source]

Records a change to a user’s saved meal item.

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

Parameters:
  • 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_items_get(meal_id)[source]

Returns saved meal items for a specified saved meal.

Parameters:meal_id (str) – The ID of the saved meal to retrieve the saved_meal_items for.
static unix_time(dt)[source]

Convert the provided datetime into number of days since the Epoch

Parameters:dt (datetime.datetime) – Date to convert
static valid_response(response)[source]

Helper function to check JSON response for errors and to strip headers

Parameters:response (requests.Response) – JSON response from API call
weight_update(current_weight_kg, date=None, weight_type='kg', height_type='cm', goal_weight_kg=None, current_height_cm=None, comment=None)[source]

Records a user’s weight for a nominated date.

First time weigh-ins require the goal_weight_kg and current_height_cm parameters.

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.
weights_get_month(date=None)[source]

Returns the recorded weights for a user for the month specified. Use this call to display a user’s weight chart or log of weight changes for a nominated month.

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