This is documentation for the full nutritional API. It includes everything you will need to access both the free version of the API and the full version of the API.
Really, the only difference between the free version and the full one is the level of detail you get in the nutritional data.
In the free version you will receive nutritional labels plus calories and servings.
In the full version you will get also detailed data on 36 nutrients including fat, cholesterol, proteins, vitamins etc.
We expect that the free version will be sufficient for most use cases if you need the full one you can always apply for an upgrade.
Returns nutritional information based on a
POST request of the recipe content
The following parameters are part of the
POST request URL:
||yes||String||Your 3scale application ID|
||yes||String||Your 3scale application key|
||yes||N/A||This is an empty parameter required for backward compatibility|
You will use a POST request to submit the recipe content—more specifically the recipe title and ingredient list.
The response the API will return will contain nutritional analysis for the recipe based on the information provided.
The contents of the request must be a JSON object with the following format:
||yes||common name of the recipe|
||yes||ingredients (array of strings)|
||no||a short description of the recipe|
||no||number of servings|
||no||total time for preparation|
||no||level of difficulty|
||no||image link (absolute)|
||no||preparation instructions (free text)|
||no||type of cuisine|
||no||type of meal|
||no||type of dish|
The request must contain the header
Here is an example using curl:
This will send the
recipe.json file for processing.
Here is the contents of the
|HTTP Status code||Content-Type||Type||Description|
|200 OK||application/json||Recipe||Recipe object containing number of servings (yield), total calories for the recipe (calories), nutrient content by nutrient type (totalNutrients, totalDaily), diet and health classification (dietLabels, healthLabels)|
|404 Not Found||text/html||HTML||The specified URL was not found or couldn’t be retrieved|
|422 Uprocessable Entity||text/html||HTML||Couldn’t parse the recipe or extract the nutritional info|
|555||text/html||HTML||Recipe with insufficient quality to process correctly|
Composite types are described in terms of their JSON representation.
Throughout descriptions, the following notation is used:
enumstands for a string field that only takes on values from a pre-defined range (the range is specified where essential)
Tstands for an array of objects of type
T[*]stands for an object (associative map) whose every field (element) is of type
Note: Only a subset of the fields may be present, depending on the interface through which the recipe is obtained. Refer to the specific interface description for details.
||Number of servings|
||Total energy, kcal|
||% daily value|
||Diet labels: “balanced”, “high-protein”, “high-fiber”, “low-fat”, “low-carb”, “low-sodium”|
||Health labels: “vegan”, “vegetarian”, “dairy-free”, “low-sugar”, “low-fat-abs”, “sugar-conscious”, “fat free”, “gluten free”, “wheat free”|
||Quantity of specified units|
Nutritional Label Definitions
|High protein||More than 50% of total calories from proteins|
|Low carb||Less than 20% of total calories from carbs|
|Low fat||Less than 15% of total calories from fat|
|Balanced||Protein/Fat/Carb values in 15/35/50 ratio|
|High fiber||More than 5g fiber per serving|
|Low sodium||Less than 140mg Na per serving|
|Low sugar||No simple sugars — glucose, dextrose, galactose, fructose, sucrose, lactose, maltose|
|Sugar conscious||Less than 4g of sugar per serving|
|Low fat abs||Less than 3g of fat per serving|
|Gluten free||Free of gluten containing foods|
|Wheat free||No wheat, can have gluten though|
|Dairy-free||No dairy; no lactose|
|Vegan||No meat, poultry, fish, dairy, eggs or honey|
|Vegetarian||No meat, poultry, or fish|