Introduction

The Food Logging SDK is a fully featured meal tracking solution that allows you to create users and log meals on their behalf using images, text search and barcodes. It aims to automate food input by combining user's eating history and context with the food recognition and knowledge graph APIs to offer a higher accuracy system that's personalized to each user.

Concepts

Users

All meal logging related operations are performed on behalf of a user and must the authenticated using a User Token, which is used to determine the identity of the user.

For more info see the user administration docs.

Meals

A Meal represents a meal consumed by the user, it can include Entries and Images. For instance a meal could be composed of a salad, beverage, and dessert. Each of these will be represented by one or more entries with an image per course. 

{
    "id": "422d6199-c1b6-4037-866f-e28c1ea0b0ca",
    "title": "Oatmeal for Breakfast",
    "description": "I had oatmeal for breakfast again today. It's full of fiber.",
    "images": [],
    "entries": [],
    "is_done": true,
    "local_eaten_at_time": "2019-02-27T08:59:09.937098",
    "utc_eaten_at_time": "2019-02-27T10:59:09.937098",
    "time_created": "2019-02-27T11:27:05.971980Z",
    "time_modified": "2019-02-27T11:27:05.972097Z"
}
iduuid of the meal
titleoptional user provided title for the meal
descriptionoptional long form description of the meal, which could be used as a note
entrieslist of meal entries, which contain the item logged and selected serving size
imagesuser submitted images of the meal
is_donean optional flag to mark a meal as completely entered
local_eaten_at_timetime the meal was consumed using the current local time of the user
utc_eaten_at_timeUTC date time corresponding to the local eaten time
time_createdserver generated date time of when the meal was saved
time_modifiedserver generated date time of when the meal was last edited

Entering partial information

id is the only required field on a meal, allowing the user to mark meal consumption without having to provide all of the information upfront. This also allows you to only collect the information that's necessary for your application.

UTC and local consumption times

To handle the case of a user logging meals from multiple time zones you can set both a local and UTC eaten at time. Doing so will allow you to display the time of the day that the meal was eaten irrespective of current location.

local_eaten_at_time is also used as contextual information to improve the recommendations provided to the user based on the time of the day.

Entries

A Meal Entry consists of a Food Item and optionally additional information to indicate which nutrition fact was selected, what the serving size was and which image contains the item.

identry identifier (autogenerated uuid)
itemitem consumed (uuid)
nutrition_factid of nutrition fact selected for the given item (optional uuid)
serving_amountserving amount consumed for the selected nutrition_fact (optional float)
imageid of image that contains this entry (optional uuid)
{
  "id": "da17c010-e2b0-498d-b322-81ab3f354295",
  "item": {
    "id": "1e0d5c1a-08fd-4228-89b5-ce9675eb0133",
    "name": "Brown Rice",
    "details": "no fat added in cooking",
    "nutrition_facts": [
      {
        "id": "cf809f2a-11df-4a9d-8ad8-2c705fd50e5c",
        "item": "1e0d5c1a-08fd-4228-89b5-ce9675eb0133",
        "serving": {
          "amount": 1,
          "unit": {
            "id": "1f49b3a4-b335-492d-88b6-9f63f7ae0837",
            "singular_name": "cup",
            "abbreviated_singular_name": "cp",
            "plural_name": "cups",
            "abbreviated_plural_name": "cp",
            "measure_type": "volume",
            "granularity": null,
            "details": "US Customary Unit"
          },
          "grams": 195
        },
        "servings_per_package": null,
        "nutrition": {
          "calories": 214.5,
          ...
        },
        "is_default": true
      },
      ...
    ]
  },
  "nutrition_fact": "cf809f2a-11df-4a9d-8ad8-2c705fd50e5c",
  "serving_amount": 1.5,
  "image": "2f49b3a4-b335-492d-88b6-9f63f7ae0837",
  "time_created": "2018-03-27T07:00:59.234598Z",
  "time_modified": "2018-03-27T07:00:59.234739Z"
}

Entries without nutrition information

If your application doesn't require nutrition information an entry can be created without specifying a nutrition_fact and serving_amount.

This also makes it possible to log high level food items that don't have nutrition information, such as dessert or salad.

Item is inferred from provided Nutrition Fact

If a nutrition_fact is specified the item id can be omitted as it will be inferred from the nutrition_fact.

Assigning items to images

An image id should be provided for the entry to specify which image the item appears in. This makes it possible to display all items for a given image and enables past meal recognition.

Suggestions

When an image or item is added to a meal the response from the API includes a suggestions field that contains predictions for additional entries that have not yet been added to the meal. These suggestions are similar to the predictions provided by the food recognition endpoint but use contextual information such as user preferences, already logged items for the current meal and time of day to improve the accuracy. 

{
  "id": "ceefab10-a0a6-4c78-80a4-995e6c18d0cc",
  "url": "https://media.bite.ai/media/ce/ef/ab10-a0a6-4c78-80a4-995e6c18d0cc.jpg",
  "type": "",
  "source_url": null,
  "suggestions": {
    "images": [
      {
        "image": {
          "id": "519c66cd-f8b5-4be0-a445-941c0f85e1f7",
          "url": "https://media.bite.ai/media/51/9c/66cd-f8b5-4be0-a445-941c0f85e1f7.jpg",
          "source_url": null
        },
        "entries": [
          {
            "item": {
              "id": "ea916a99-389c-45d2-940d-44d886af9e98",
              "name": "Avocado"
            },
            "serving_amount": 0.5,
            "nutrition": "aaf734e1-6b2b-49ea-82e4-dc745126084b"
          }
        ],
        "score": 0.2260914806461778
      }
    ],
    "entries": [
      {
        "entry": {
          "item": {
            "id": "ea916a99-389c-45d2-940d-44d886af9e98",
            "name": "Avocado"
          },
          "serving_amount": 0.5,
          "nutrition": "aaf734e1-6b2b-49ea-82e4-dc745126084b"
        },
        "score": 1
      }
    ],
    "items": [
      {
        "item": {
          "id": "ea916a99-389c-45d2-940d-44d886af9e98",
          "name": "Avocado"
        },
        "score": 0.18991
      },
      {
        "item": {
          "id": "4f941073-def2-4be7-8147-cd706514bb10",
          "name": "Egg"
        },
        "score": 0.11009
      }
    ]
  }
}
imageslist of similar looking images that were previously logged by the user along with the entries that were assigned to those images, making it possible to let a user copy a previously logged meal
entriesentries with the item and serving amount, allowing the user to add the item without having to manually specify the serving size
itemsrecognized items in the same format as the food recognition API

Images

Images can be uploaded by file, base64 encoding, multipart form, or by url reference. See inputting images into the API for more information. Once uploaded they can analyzed using the vision endpoints or added to a meal for suggestions.