Documentation for Calorie Mama Food Recognition API

Table of Contents

  1. Guide to Uploading Images
  2. Curl - Example POST
  3. Required steps to POST to Food Recognition API
  4. Http Headers and Response Codes
  5. Parsing and Understanding JSON Response
  6. Android Example on GitHub.Click here

Guide to Uploading Images

Images must meet following criteria: - Supported media type: JPEG - Image size: 544x544 px

The file limits above are enforced by the Food Recognition API endpoint

Example POST: Food Recognition from Image

Expected return is a JSON with recognized food results.

curl -H -i -F media=@image.jpeg https://api-2445582032290.production.gw.apicast.io/v1/foodrecognition?user_key=YOUR KEY HERE

You can also post an image with Content-Type image/jpeg

curl --request POST -H "Content-Type: image/jpeg" --data-binary "@image.jpeg" https://api-2445582032290.production.gw.apicast.io/v1/foodrecognition?user_key=YOUR KEY HERE

Required steps to POST to Food Recognition API

  1. Crop image to 544x544 px (crop in the center of image)
  2. Send with Content-Type multipart/form-data or image/jpeg request to recognition endpoint /v1/foodrecognition
  3. Parse JSON recognition results

Error Response Codes

All responses have the same JSON format.

Error codes

400 Bad Request

401 Authorization failure

404 Not found

500 Server side error

Each code will have a json attached with description of the error

{
    "error": {
        "errorDetail": "Not photo attached",
        "code": 400
    }
}

 

Nutritional info

All units are in kg.

Available fields are:

Full nutrition API /v1/foodrecognition/full

  • calories
  • totalFat
  • transFat
  • cholesterol
  • sodium
  • totalCarbs
  • saturatedFat
  • dietaryFiber
  • sugars
  • protein
  • monounsaturatedFat
  • polyunsaturatedFat
  • vitaminA
  • vitaminC
  • iron
  • potassium
  • calcium

Macronutrients API /v1/foodrecognition

  • calories
  • totalFat
  • totalCarbs
  • protein

JSON Response

Json Decomposition

Results are grouped under the main food category (e.g. Bacon, Salad, ...). Each group contains multiple items corresponding to specific group.

The only "special" group is Packaged Food. Packaged Food group is returned only in case when Food Recognition API thinks that the item might be a packaged food. The group is also marked with a flag: packagedgoods=true.

Structure of returned JSON

Json Decomposed 1

Structure of particular food item

Json Decomposed 2

Understanding the JSON response

Looking at Example response Here we have to keep in mind all values are in basic SI units.

Example response

All values are in basic SI units (kg,second,meter...) http://en.wikipedia.org/wiki/InternationalSystemof_Units

{
    "model": "20170209",
    "results": [{
            "packagedgoods": true,
            "group": "Packaged Good",
            "items": [{
                "nutrition": {
                    "totalCarbs": 0.875,
                    "protein": 0.0125,
                    "calories": 3500,
                    "sodium": 0.003,
                    "iron": 9.0E-6,
                    "sugars": 0.625
                },
                "name": "Licorice Candy",
                "score": 6,
                "brand": "Good & Plenty",
                "servingSizes": [{
                    "unit": "33.0 pieces",
                    "servingWeight": 0.04
                }]
            }, {
                "nutrition": {
                    "totalCarbs": 0.8461538461538461,
                    "calories": 3333.3333333333335,
                    "sodium": 0.0023076923076923075,
                    "iron": 9.23076923076923E-6,
                    "sugars": 0.5384615384615384
                },
                "name": "Licorice Candy",
                "score": 10,
                "brand": "Good & Plenty",
                "servingSizes": [{
                    "unit": "33.0 pieces",
                    "servingWeight": 0.039
                }]
            }]
        }, {
            "group": "Bacon",
            "items": [{
                "score": 87,
                "name": "Bacon",
                "nutrition": {
                    "calcium": 1.1000000000000002E-4,
                    "saturatedFat": 0.13739,
                    "monounsaturatedFat": 0.18519999999999998,
                    "sodium": 0.0103,
                    "totalFat": 0.4178,
                    "cholesterol": 0.0011,
                    "iron": 1.4400000000000001E-5,
                    "polyunsaturatedFat": 0.04548000000000001,
                    "totalCarbs": 0.014299999999999998,
                    "protein": 0.37039999999999995,
                    "potassium": 0.0056500000000000005,
                    "vitaminA": 1.11E-7,
                    "calories": 5410
                },
                "servingSizes": [{
                    "unit": "1 slice, cooked",
                    "servingWeight": 0.008
                }, {
                    "unit": "100 g",
                    "servingWeight": 0.1
                }, {
                    "unit": "1 g",
                    "servingWeight": 0.001
                }, {
                    "unit": "1 oz",
                    "servingWeight": 0.0283495
                }]
            }, {
                "generic": true,
                "score": 1,
                "name": "Bacon (any kind)",
                "nutrition": {
                    "calcium": 1.1000000000000002E-4,
                    "saturatedFat": 0.13739,
                    "monounsaturatedFat": 0.18519999999999998,
                    "sodium": 0.0103,
                    "totalFat": 0.4178,
                    "cholesterol": 0.0011,
                    "iron": 1.4400000000000001E-5,
                    "polyunsaturatedFat": 0.04548000000000001,
                    "totalCarbs": 0.014299999999999998,
                    "protein": 0.37039999999999995,
                    "potassium": 0.0056500000000000005,
                    "vitaminA": 1.11E-7,
                    "calories": 5410
                },
                "servingSizes": [{
                    "unit": "1 slice, cooked",
                    "servingWeight": 0.008
                }, {
                    "unit": "100 g",
                    "servingWeight": 0.1
                }, {
                    "unit": "1 g",
                    "servingWeight": 0.001
                }, {
                    "unit": "1 oz",
                    "servingWeight": 0.0283495
                }]
            }]
        },
        {
            "group": "Confection",
            "items": [{
                "score": 77,
                "name": "Brownie",
                "servingSizes": [{
                    "unit": "1 brownie (2\" square)",
                    "servingWeight": 0.024
                }, {
                    "unit": "1 oz",
                    "servingWeight": 0.02835
                }, {
                    "unit": "100 g",
                    "servingWeight": 0.1
                }, {
                    "unit": "1 g",
                    "servingWeight": 0.001
                }],
                "nutrition": {
                    "calcium": 5.700000000000001E-4,
                    "vitaminC": 3.0E-6,
                    "saturatedFat": 0.07318999999999999,
                    "monounsaturatedFat": 0.10839,
                    "sodium": 0.0034300000000000003,
                    "totalFat": 0.291,
                    "cholesterol": 7.3E-4,
                    "iron": 1.8399999996000002E-5,
                    "polyunsaturatedFat": 0.09412000000000001,
                    "totalCarbs": 0.502,
                    "protein": 0.062,
                    "potassium": 0.00176,
                    "vitaminA": 2.481E-6,
                    "calories": 4660
                }
            }]
        }
    ]
}