Food

This resource helps create custom foods that profiles can quickly add to their FoodDiary. On this page, we'll dive into the different food endpoints you can use to manage food for profiles programmatically. We'll look at how to query, create, delete food items.

The `Food` model

The food model contains detailed nutritional information for the specified food for each available standard serving size.

Properties

Name
_id
Type
objectID
Description
Unique food identifier
Name
food_name
Type
string
Description
Name of the food, not including the brand name. E.G.: "Instant Oatmeal"
Name
food_type
Type
generic | brand
Description
Takes the value brand or generic. Indicates whether the food is a brand or generic item
Name
brand_name
Type
null | string
Description
Brand name, only when food_type=brand. E.G.: "Quaker"
Name
serving_description
Type
string
Description
Full description of the serving size. E.G.: "1 cup" or "100 g"
Name
metric_serving_amount
Type
int
Description
Metric quantity combined with metric_serving_unit to derive the total standardized quantity of the serving (where available)
Name
metric_serving_unit
Type
g | ml | oz
Description
Metric unit of measure for the serving size – either g or ml or oz – combined with metric_serving_amount to derive the total standardized quantity of the serving (where available)
Name
macro_nutrients
Type
object
Description
General macro-nutrients for the food.
Name
water_in_gm
Type
float
Description
Water content in grams
Name
vitamins
Type
object
Description
All vitamins in the food.
Name
minerals
Type
object
Description
All minerals in the food.
Name
carbohydrates
Type
object
Description
All applicable carbohydrates in the food.
Name
lipids
Type
object
Description
All applicable lipids in the food.
Name
proteins
Type
object
Description
All applicable proteins in the food.
Name
profile_reference_id
Type
null | objectID
Description
If this is a custom Food defined by a profile, there will be an reference_id of the profile.
Name
created_at
Type
datetime
Description
Name
updated_at
Type
datetime
Description

GET/v1/foods/barcode

Retrieve food from barcode

This endpoint allows you to retrieve a food matching the barcode specified. By default the endpoint doesn't return vitamins, minerals, carbohydrates, lipids, proteins. You may use the includes parameter to specify if you want the additional nutrient information.

Parameters

Name
barcode
Type
string
Required Parameter
* Required
Description
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).
Name
include
Type
string array
Description
Defaults to []
Possible values are as follows:
vitamins | minerals | carbohydrates | lipids | proteins

Request

GET

/v1/foods/barcode

curl -G https://api.zenreal.app/v1/foods/barcode \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d "barcode"="8901058851298" \
  -d "include[]"="vitamins"

Response

{
    "_id": "hSIhXBhNe8X1d8Et",
    "food_name": "Maggi",
    "food_type": "brand",
    "brand_name": "Nestlé",
    "serving_description": "1 brick",
    "metric_serving_amount": 70,
    "metric_serving_unit": "g",
    "macro_nutrients": {...},
    "water_in_gm": 0,
    "vitamins": {...},
    "profile_reference_id": null
}

GET/v1/foods/:id

Retrieve food

This endpoint allows you to retrieve a food by providing their _id. By default the endpoint doesn't return vitamins, minerals, carbohydrates, lipids, proteins. You may use the includes parameter to specify if you want the additional nutrient information.

Parameters

Name
include
Type
string array
Description
Defaults to []
Possible values are as follows:
vitamins | minerals | carbohydrates | lipids | proteins

Request

GET

/v1/foods/hSIhXBhNe8X1d8Et

curl -G https://api.zenreal.app/v1/foods/hSIhXBhNe8X1d8Et \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d "include[]"="vitamins"

Response

{
    "_id": "hSIhXBhNe8X1d8Et",
    "food_name": "Nutrition Bar by Zeke",
    "food_type": "generic",
    "brand_name": null,
    "serving_description": "1 bar",
    "metric_serving_amount": 100,
    "metric_serving_unit": "g",
    "macro_nutrients": {...},
    "water_in_gm": 0,
    "vitamins": {...},
    "profile_reference_id": "WAz8eIbvDR60rouK"
}

GET/v1/foods/search

Search foods

This endpoint allows you to conducts a search of the food database using the search expression specified.

Parameters

Name
query
Type
string
Required Parameter
* Required
Description
Search expression to match on food names
Name
starting_after
Type
objectID
Description
The last ID on the page you're currently on when you want to fetch the next page.
Name
ending_before
Type
objectID
Description
The first ID on the page you're currently on when you want to fetch the previous page.
Name
limit
Type
int
Description
Limit the number of items returned.

Request

GET

/v1/foods/search

curl -G https://api.zenreal.app/v1/foods/search \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d query="Apple"

Response

{
    "has_more": true,
    "data": [
        {
            "_id": "gEajUVhLo4Y3f9FR",
            "food_name": "Apple",
            "food_type": "generic",
            "brand_name": null,
            "serving_description": "1 piece",
            "metric_serving_amount": 150,
            "metric_serving_unit": "g",
            "macro_nutrients": {...},
            "water_in_gm": 0,
            "profile_reference_id": null
        },
        {
            // ...
        }
    ]
}

POST/v1/foods/custom

Create custom food

This endpoint allows you to create a food for a profile according to the parameters specified. The result of the call is the new unique identifier of the newly created food.

Parameters

Name
food_name
Type
string
Required Parameter
* Required
Description
Name of the food, not including the brand name. E.G.: "Instant Oatmeal"
Name
serving_description
Type
string
Required Parameter
* Required
Description
Full description of the serving size. E.G.: "1 cup" or "100 g"
Name
metric_serving_amount
Type
int
Required Parameter
* Required
Description
Metric quantity combined with metric_serving_unit to derive the total standardized quantity of the serving (where available)
Name
metric_serving_unit
Type
g | ml | oz
Required Parameter
* Required
Description
Metric unit of measure for the serving size – either g or ml or oz – combined with metric_serving_amount to derive the total standardized quantity of the serving (where available)
Name
profile_reference_id
Type
string
Required Parameter
* Required
Description
Provide unique reference for a profile.
Name
food_type
Type
generic | brand
Description
Defaults to generic
Takes the value brand or generic. Indicates whether the food is a brand or generic item
Name
brand_name
Type
nullable string
Description
Brand name, only when food_type=brand. E.G.: "Quaker"
Name
macro_nutrients
Type
object
Description
General macro-nutrients for the food.
Name
water_in_gm
Type
float
Description
Water content in grams
Name
vitamins
Type
object
Description
All vitamins in the food.
Name
minerals
Type
object
Description
All minerals in the food.
Name
carbohydrates
Type
object
Description
All applicable carbohydrates in the food.
Name
lipids
Type
object
Description
All applicable lipids in the food.
Name
proteins
Type
object
Description
All applicable proteins in the food.

Request

POST

/v1/foods/custom

curl https://api.zenreal.app/v1/foods/custom \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d food_name="Nutrition Bar by Zeke" \
  -d serving_description="1 bar" \
  -d metric_serving_amount=100 \
  -d metric_serving_unit="g" \
  -d profile_reference_id="WAz8eIbvDR60rouK" \
  -d macro_nutrients[energy_kcal]=350

Response

{
    "_id": "hSIhXBhNe8X1d8Et",
    "created": true
}

DELETE/v1/foods/custom/:id

Delete custom food

This endpoint allows you to delete a custom food created by a profile.

Parameters

Name
profile_reference_id
Type
string
Required Parameter
* Required
Description
Provide reference for the profile that the food belongs to.

Request

DELETE

/v1/foods/custom/hSIhXBhNe8X1d8Et

curl -X DELETE -G https://api.zenreal.app/v1/foods/custom/hSIhXBhNe8X1d8Et \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d profile_reference_id="WAz8eIbvDR60rouK"

Response

{
    "_id": "hSIhXBhNe8X1d8Et",
    "deleted": true
}

GET/v1/foods/favorites

List favorite foods

This endpoint allows you to list the favorite foods for the specified profile.

Parameters

Name
profile_reference_id
Type
string
Required Parameter
* Required
Description
Provide unique reference for a profile.
Name
starting_after
Type
objectID
Description
The last ID on the page you're currently on when you want to fetch the next page.
Name
ending_before
Type
objectID
Description
The first ID on the page you're currently on when you want to fetch the previous page.
Name
limit
Type
int
Description
Limit the number of items returned.

Request

GET

/v1/foods/favorites

curl -G https://api.zenreal.app/v1/foods/favorites \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d profile_reference_id="WAz8eIbvDR60rouK"

Response

{
    "has_more": true,
    "data": [
        {
            "_id": "hSIhXBhNe8X1d8Et",
            "food_name": "Maggi",
            "food_type": "brand",
            "brand_name": "Nestlé",
            "serving_description": "1 brick",
            "metric_serving_amount": 70,
            "metric_serving_unit": "g",
            "macro_nutrients": {...},
            "water_in_gm": 0,
            "vitamins": {...},
            "profile_reference_id": null
        },
        {
            // ...
        }
    ]
}

POST/v1/foods/favorites/:id

Add favorite food

This endpoint allows you to add a food to a profile's favorite list.

Parameters

Name
profile_reference_id
Type
string
Required Parameter
* Required
Description
Provide unique reference for a profile.

Request

POST

/v1/foods/favorites/hSIhXBhNe8X1d8Et

curl https://api.zenreal.app/v1/foods/favorites/hSIhXBhNe8X1d8Et \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d profile_reference_id="WAz8eIbvDR60rouK"

Response

{
    "_id": "hSIhXBhNe8X1d8Et",
    "created": true
}

DELETE/v1/foods/favorites/:id

Remove favorite food

This endpoint allows you to remove a food from a profile's favorite list.

Parameters

Name
profile_reference_id
Type
string
Required Parameter
* Required
Description
Provide unique reference for a profile.

Request

DELETE

/v1/foods/favorites/hSIhXBhNe8X1d8Et

curl -X DELETE _G https://api.zenreal.app/v1/foods/favorites/hSIhXBhNe8X1d8Et \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d profile_reference_id="WAz8eIbvDR60rouK"

Response

{
    "_id": "hSIhXBhNe8X1d8Et",
    "deleted": true
}

GET/v1/foods/recently-eaten

List recently eaten

This endpoint allows you to list the recently logged foods for the specified profile.

Parameters

Name
profile_reference_id
Type
string
Required Parameter
* Required
Description
Provide unique reference for a profile.
Name
starting_after
Type
objectID
Description
The last ID on the page you're currently on when you want to fetch the next page.
Name
ending_before
Type
objectID
Description
The first ID on the page you're currently on when you want to fetch the previous page.
Name
limit
Type
int
Description
Limit the number of items returned.

Request

GET

/v1/foods/recently-eaten

curl -G https://api.zenreal.app/v1/foods/recently-eaten \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d profile_reference_id="WAz8eIbvDR60rouK"

Response

{
    "has_more": true,
    "data": [
        {
            "_id": "hSIhXBhNe8X1d8Et",
            "food_name": "Maggi",
            "food_type": "brand",
            "brand_name": "Nestlé",
            "serving_description": "1 brick",
            "metric_serving_amount": 70,
            "metric_serving_unit": "g",
            "macro_nutrients": {...},
            "water_in_gm": 0,
            "vitamins": {...},
            "profile_reference_id": null
        },
        {
            // ...
        }
    ]
}

GET/v1/foods/most-eaten

List most eaten

This endpoint allows you to list the most logged foods in the past 30 day period for the specified profile.

Parameters

Name
profile_reference_id
Type
string
Required Parameter
* Required
Description
Provide unique reference for a profile.
Name
starting_after
Type
objectID
Description
The last ID on the page you're currently on when you want to fetch the next page.
Name
ending_before
Type
objectID
Description
The first ID on the page you're currently on when you want to fetch the previous page.
Name
limit
Type
int
Description
Limit the number of items returned.

Request

GET

/v1/foods/most-eaten

curl -G https://api.zenreal.app/v1/foods/most-eaten \
  -H "Authorization: Bearer {YOUR_API_KEY}" \
  -d profile_reference_id="WAz8eIbvDR60rouK"

Response

{
    "has_more": true,
    "data": [
        {
            "_id": "hSIhXBhNe8X1d8Et",
            "food_name": "Maggi",
            "food_type": "brand",
            "brand_name": "Nestlé",
            "serving_description": "1 brick",
            "metric_serving_amount": 70,
            "metric_serving_unit": "g",
            "macro_nutrients": {...},
            "water_in_gm": 0,
            "vitamins": {...},
            "profile_reference_id": null
        },
        {
            // ...
        }
    ]
}