API Documentation

As of v1.0 every endpoint method carries an explicit _vN suffix matching the upstream API version (e.g. foods_search_v5, food_get_v5, recipes_search_v3). The unsuffixed legacy names (foods_search, food_get, …) remain available as deprecated aliases for the v1.x line and emit DeprecationWarning when called. To surface those warnings during development, run Python with:

python -W default::DeprecationWarning:fatsecret

The endpoint methods below are exposed via resource sub-objects on a fatsecret.Fatsecret instance – e.g. fs.foods.search_v5(...) – and are grouped by their OpenAPI tag (sourced from docs/api-spec/openapi.generated.yaml). Client-only helpers (auth handshake, session lifecycle, time conversion) are listed at the bottom under Client utilities.

Exercise Diary Entries

Fatsecret.exercises.entries_commit_day_v1()

ExercisesResource.entries_commit_day_v1(date: int | None = None) → bool

exercise_entries.commit_day (v1). Premier-only.

Fatsecret.exercises.entries_get_month_v1()

ExercisesResource.entries_get_month_v1(date: int | None = None) → list

exercise_entries.get_month (v1). DEPRECATED upstream. Premier-only.

Fatsecret.exercises.entries_get_month_v2()

ExercisesResource.entries_get_month_v2(date: int | None = None) → list

exercise_entries.get_month (v2). Premier-only.

Fatsecret.exercises.entries_get_v1()

ExercisesResource.entries_get_v1(date: int | None = None) → list

exercise_entries.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.exercises.entries_get_v2()

ExercisesResource.entries_get_v2(date: int | None = None) → list

exercise_entries.get (v2). Premier-only.

Fatsecret.exercises.entries_save_template_v1()

ExercisesResource.entries_save_template_v1(days: int, date: datetime | date | int | float | None = None)

exercise_entries.save_template (v1). Premier-only.

Exercise Diary Entry

Fatsecret.exercises.entry_edit_v1()

ExercisesResource.entry_edit_v1(shift_to_id: int, shift_from_id: int, minutes: int, date: int | None = None, shift_to_name: str | None = None, shift_from_name: str | None = None, kcal: int | None = None) → bool

exercise_entry.edit (v1). Premier-only.

Exercises

Fatsecret.exercises.list_v1()

ExercisesResource.list_v1(region: str | None = None, language: str | None = None) → list

exercises.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.exercises.list_v2()

ExercisesResource.list_v2(region: str | None = None, language: str | None = None) → list

exercises.get (v2). Premier-only.

Feedback

Fatsecret.feedback.submit_v1()

FeedbackResource.submit_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). Premier-only.

Food

Fatsecret.profile_foods.add_favorite_v1()

ProfileFoodsResource.add_favorite_v1(food_id: int, serving_id: int | None = None, number_of_units: float | None = None) → bool

food.add_favorite (v1). Premier-only.

Fatsecret.profile_foods.create_v1()

ProfileFoodsResource.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-only.

Fatsecret.profile_foods.create_v2()

ProfileFoodsResource.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). Premier-only.

Fatsecret.profile_foods.delete_favorite_v1()

ProfileFoodsResource.delete_favorite_v1(food_id: int, serving_id: int | None = None, number_of_units: float | None = None) → bool

food.delete_favorite (v1). Premier-only.

Fatsecret.foods.find_id_for_barcode_v1()

FoodsResource.find_id_for_barcode_v1(barcode: str, region: str | None = None, language: str | None = None) → Any

food.find_id_for_barcode (v1). Premier-only.

Fatsecret.foods.find_id_for_barcode_v2()

FoodsResource.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) → Any

food.find_id_for_barcode (v2). Premier-only.

Fatsecret.foods.get_v1()

FoodsResource.get_v1(food_id: int, include_sub_categories: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → Any

food.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.foods.get_v2()

FoodsResource.get_v2(food_id, region=None, language=None)

Returns detailed nutritional information for the specified food.

Parameters:

food_id (str) – Fatsecret food identifier

Fatsecret.foods.get_v3()

FoodsResource.get_v3(food_id: int, include_sub_categories: bool | None = None, flag_default_serving: bool | None = None, region: str | None = None, language: str | None = None) → Any

food.get (v3). DEPRECATED upstream. Premier-only.

Fatsecret.foods.get_v4()

FoodsResource.get_v4(food_id: int, 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) → Any

food.get (v4). DEPRECATED upstream. Premier-only.

Fatsecret.foods.get_v5()

FoodsResource.get_v5(food_id: int, 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) → Any

food.get (v5). Premier-only.

Food Brands

Fatsecret.classification.brands_get_v1()

ClassificationResource.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-only.

Fatsecret.classification.brands_get_v2()

ClassificationResource.brands_get_v2(starts_with: str, brand_type: str | None = None, region: str | None = None, language: str | None = None) → list

food_brands.get (v2). Premier-only.

Food Categories

Fatsecret.classification.categories_get_v1()

ClassificationResource.categories_get_v1(region: str | None = None, language: str | None = None) → list

food_categories.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.classification.categories_get_v2()

ClassificationResource.categories_get_v2(region: str | None = None, language: str | None = None) → list

food_categories.get (v2). Premier-only.

Food Diary Entries

Fatsecret.diary.entries_copy_saved_meal_v1()

DiaryResource.entries_copy_saved_meal_v1(saved_meal_id: int, meal: str, date: int | None = None) → bool

food_entries.copy_saved_meal (v1). Premier-only.

Fatsecret.diary.entries_copy_v1()

DiaryResource.entries_copy_v1(from_date: int, to_date: int, meal: str | None = None) → bool

food_entries.copy (v1). Premier-only.

Fatsecret.diary.entries_get_month_v1()

DiaryResource.entries_get_month_v1(date: int | None = None) → list

food_entries.get_month (v1). DEPRECATED upstream. Premier-only.

Fatsecret.diary.entries_get_month_v2()

DiaryResource.entries_get_month_v2(date: int | None = None) → list

food_entries.get_month (v2). Premier-only.

Fatsecret.diary.entries_get_v1()

DiaryResource.entries_get_v1(food_entry_id: str | None = None, date: datetime | date | int | float | None = None)

food_entries.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.diary.entries_get_v2()

DiaryResource.entries_get_v2(food_entry_id: str | None = None, date: datetime | date | int | float | None = None)

food_entries.get (v2). Premier-only.

Food Diary Entry

Fatsecret.diary.entry_create_v1()

DiaryResource.entry_create_v1(food_id: int, food_entry_name: str, serving_id: int, number_of_units: float, meal: str, date: int | None = None) → list

food_entry.create (v1). Premier-only.

Fatsecret.diary.entry_delete_v1()

DiaryResource.entry_delete_v1(food_entry_id: int) → bool

food_entry.delete (v1). Premier-only.

Fatsecret.diary.entry_edit_v1()

DiaryResource.entry_edit_v1(food_entry_id: int, food_entry_name: str | None = None, serving_id: int | None = None, number_of_units: float | None = None, meal: str | None = None) → bool

food_entry.edit (v1). Premier-only.

Food Sub-Categories

Fatsecret.classification.sub_categories_get_v1()

ClassificationResource.sub_categories_get_v1(food_category_id: int, region: str | None = None, language: str | None = None) → list

food_sub_categories.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.classification.sub_categories_get_v2()

ClassificationResource.sub_categories_get_v2(food_category_id: int, region: str | None = None, language: str | None = None) → list

food_sub_categories.get (v2). Premier-only.

Foods (search, autocomplete, favorites)

Fatsecret.foods.autocomplete_v1()

FoodsResource.autocomplete_v1(expression: str, max_results: int | None = None, region: str | None = None) → list

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

Fatsecret.foods.autocomplete_v2()

FoodsResource.autocomplete_v2(expression: str, max_results: int | None = None, region: str | None = None) → list

foods.autocomplete (v2). Premier-only.

Fatsecret.profile_foods.get_favorites_v1()

ProfileFoodsResource.get_favorites_v1() → list

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

Fatsecret.profile_foods.get_favorites_v2()

ProfileFoodsResource.get_favorites_v2() → list

foods.get_favorites (v2). Premier-only.

Fatsecret.profile_foods.get_most_eaten_v1()

ProfileFoodsResource.get_most_eaten_v1(meal: str | None = None) → list

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

Fatsecret.profile_foods.get_most_eaten_v2()

ProfileFoodsResource.get_most_eaten_v2(meal: str | None = None) → list

foods.get_most_eaten (v2). Premier-only.

Fatsecret.profile_foods.get_recently_eaten_v1()

ProfileFoodsResource.get_recently_eaten_v1(meal: str | None = None) → list

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

Fatsecret.profile_foods.get_recently_eaten_v2()

ProfileFoodsResource.get_recently_eaten_v2(meal: str | None = None) → list

foods.get_recently_eaten (v2). Premier-only.

Fatsecret.foods.search_v1()

FoodsResource.search_v1(search_expression: str | None = None, 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). Premier-only.

Fatsecret.foods.search_v2()

FoodsResource.search_v2(search_expression: str | None = None, 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. Premier-only.

Fatsecret.foods.search_v3()

FoodsResource.search_v3(search_expression: str | None = None, 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. Premier-only.

Fatsecret.foods.search_v4()

FoodsResource.search_v4(search_expression: str | None = None, 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. Premier-only.

Fatsecret.foods.search_v5()

FoodsResource.search_v5(search_expression: str | None = None, 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). Premier-only.

Image Recognition

Fatsecret.native.image_recognition_v1()

NativeResource.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). Premier-only.

Fatsecret.native.image_recognition_v2()

NativeResource.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). Premier-only.

Natural Language Processing

Fatsecret.native.natural_language_processing_v1()

NativeResource.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). Premier-only.

Profile

Fatsecret.profile.create_v1()

ProfileResource.create_v1(user_id: str) → Any

profile.create (v1). Premier-only.

Fatsecret.profile.get_auth_v1()

ProfileResource.get_auth_v1(user_id: str | None = None) → Any

profile.get_auth (v1). Premier-only.

Fatsecret.profile.get_v1()

ProfileResource.get_v1() → Any

profile.get (v1). Premier-only.

Recipe

Fatsecret.recipes.add_favorite_v1()

RecipesResource.add_favorite_v1(recipe_id: str)

recipe.add_favorite (v1). Premier-only.

Fatsecret.recipes.delete_favorite_v1()

RecipesResource.delete_favorite_v1(recipe_id: str)

recipe.delete_favorite (v1). Premier-only.

Fatsecret.recipes.get_v1()

RecipesResource.get_v1(recipe_id: int, region: str | None = None) → Any

recipe.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.recipes.get_v2()

RecipesResource.get_v2(recipe_id: int, region: str | None = None) → Any

recipe.get (v2). Premier-only.

Recipe Types

Fatsecret.recipes.types_get_v1()

RecipesResource.types_get_v1() → list

recipe_types.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.recipes.types_get_v2()

RecipesResource.types_get_v2(region: str | None = None, language: str | None = None) → list

recipe_types.get (v2). Premier-only.

Recipes

Fatsecret.recipes.get_favorites_v1()

RecipesResource.get_favorites_v1() → list

recipes.get_favorites (v1). DEPRECATED upstream. Premier-only.

Fatsecret.recipes.get_favorites_v2()

RecipesResource.get_favorites_v2() → list

recipes.get_favorites (v2). Premier-only.

Fatsecret.recipes.search_v1()

RecipesResource.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. Premier-only.

Fatsecret.recipes.search_v2()

RecipesResource.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. Premier-only.

Fatsecret.recipes.search_v3()

RecipesResource.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). Premier-only.

Saved Meal

Fatsecret.meals.create_v1()

MealsResource.create_v1(saved_meal_name: str, saved_meal_description: str | None = None, meals: str | None = None) → Any

saved_meal.create (v1). Premier-only.

Fatsecret.meals.delete_v1()

MealsResource.delete_v1(saved_meal_id: int) → bool

saved_meal.delete (v1). Premier-only.

Fatsecret.meals.edit_v1()

MealsResource.edit_v1(saved_meal_id: int, saved_meal_name: str | None = None, saved_meal_description: str | None = None, meals: str | None = None) → bool

saved_meal.edit (v1). Premier-only.

Saved Meal Item

Fatsecret.meals.item_add_v1()

MealsResource.item_add_v1(saved_meal_id: int, food_id: int, saved_meal_item_name: str, serving_id: int, number_of_units: float) → Any

saved_meal_item.add (v1). Premier-only.

Fatsecret.meals.item_delete_v1()

MealsResource.item_delete_v1(saved_meal_item_id: int) → bool

saved_meal_item.delete (v1). Premier-only.

Fatsecret.meals.item_edit_v1()

MealsResource.item_edit_v1(saved_meal_item_id: int, saved_meal_item_name: str | None = None, number_of_units: float | None = None) → bool

saved_meal_item.edit (v1). Premier-only.

Saved Meal Items

Fatsecret.meals.items_get_v1()

MealsResource.items_get_v1(saved_meal_id: int) → list

saved_meal_items.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.meals.items_get_v2()

MealsResource.items_get_v2(saved_meal_id: int) → list

saved_meal_items.get (v2). Premier-only.

Saved Meals

Fatsecret.meals.get_v1()

MealsResource.get_v1(meal: str | None = None) → list

saved_meals.get (v1). DEPRECATED upstream. Premier-only.

Fatsecret.meals.get_v2()

MealsResource.get_v2(meal: str | None = None) → list

saved_meals.get (v2). Premier-only.

Weight

Fatsecret.weight.update_v1()

WeightResource.update_v1(current_weight_kg: float, date: int | 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

weight.update (v1). Premier-only.

Weights (history)

Fatsecret.weight.get_month_v1()

WeightResource.get_month_v1(date: int | None = None) → list

weights.get_month (v1). DEPRECATED upstream. Premier-only.

Fatsecret.weight.get_month_v2()

WeightResource.get_month_v2(date: int | None = None) → list

weights.get_month (v2). Premier-only.

Client utilities

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

Fatsecret.close() → None

Close the current HTTP session.

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

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

Fetch an OAuth1 request token and return the user-facing authorize URL.

Args:

callback_url: Absolute URL to redirect the user to after they authorize,

or "oob" (out-of-band) to receive a verifier PIN.

Returns:

The authorize URL with the freshly minted oauth_token appended.

static Fatsecret.unix_time(dt: datetime) → int

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

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

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

static Fatsecret.valid_response(response: Response)

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