Page Overview
GET /api/v1/recipe/profiles
The Recipe Profiles API is a solution designed to return the dietary profile and composition of the ingredients in a recipe given their respective quantities. Only an ingredient list in the form of a JSON array is a required element to be passed in the API body as the payload. A composition parameter can be passed through with multiple arguments to define the desired composition data to be returned in overall recipe values for all ingredients combined. Finally, a language parameter may also be provided to specify the language of the provided ingredients.
Recipe Profiles API Request
Below is an overview of the construction a Recipe Profiles API request with examples provided.
Required Inputs
The Recipe Profiles API request must contain authorization through the header as well as declaration of the json content type of the payload.
API Headers
Header | Type | Example | |
---|---|---|---|
Authorization | string | Authorization: Token <YOUR_BONAPI_TOKEN> | required |
Content-type | string | application/json | required |
API Request Body application/json
The payload consists of he ingredients which are provided in a JSON format object under the key "ingredients" with its value pair as an array containing the ingredients.
data={"ingredients": <array of ingredients>}
The ingredients are provided through the payload in the API body, provided in an array where each element is a separate ingredient entry. Ingredients should be provided with their respective quantities as well as with some descriptive and processing information if present: for example “1 cup of finely chopped Onion” or “2 large potatoes” as these allow for identifying the quantity of that ingredient.
Input | Type | Description | |
---|---|---|---|
Ingredients | array | Ingredients must be provided in a JSON formatted array, where each element is an individual ingredient or item in an ingredient list. | required |
Example ingredients array:
['250gr white wheat flour', '50ml cow milk', '1 chicken breast', '0.5 cups of white rice']
Query Parameters
Parameters can be provided to define which composition data should be returned and in what language the ingredients are being provided in. Parameters can be declared in any order, and their arguments should be provided using the keys defined in the Reference APIs and Support and shown below. Multiple parameters can be passed through joined by an ampersand (&).
/api/v1/recipe/profiles/?diet=
The diet parameter accepts one argument and defines the diet that the recipe must conform to. A diet is understood to be conformed to if all ingredients fall within it or a more restrictive diet: for example cow’s milk (vegetarian) is understood to also conform to a Pescetarian and unrestricted (Meat-eater) diet and would only be substituted if a vegan parameter was provided.
Arguments | Type | Description | |
---|---|---|---|
pescetarian | string | Requires that results must be suitable for a pescetarian diet. | optional |
vegetarian | string | Requires that results must be suitable for a vegetarian diet. | optional |
vegan | string | Requires that results must be suitable for a vegan diet. | optional |
Example diet parameter:
/api/v1/recipe/profiles/?allergies=
The allergies parameter accepts multiple arguments and defines any allergies or intolerances that the ingredients must no longer contain. Multiple arguments are joined with a comma (' , '). Any ingredients containing any of the provided allergies or intolerances will be substituted with viable alternatives.
Arguments | Type | Description | |
---|---|---|---|
celery_allergy | string | Requires that results must be suitable for a celery allergy. | optional |
crustacean_allergy | string | Requires that results must be suitable for a crustacean allergy. | optional |
egg_allergy | string | Requires that results must be suitable for an egg allergy. | optional |
fish_allergy | string | Requires that results must be suitable for a fish allergy. | optional |
gluten_allergy | string | Requires that results must be suitable for a gluten allergy (Celiac disease). | optional |
lactose_intolerance | string | Requires that results must be suitable for a lactose intolerance. | optional |
lupin_allergy | string | Requires that results must be suitable for a lupin allergy. | optional |
milk_allergy | string | Requires that results must be suitable for a milk allergy. | optional |
mollusc_allergy | string | Requires that results must be suitable for a mollusc allergy. | optional |
mustard_allergy | string | Requires that results must be suitable for a mustard allergy. | optional |
peanut_allergy | string | Requires that results must be suitable for a peanut allergy. | optional |
sesame_allergy | string | Requires that results must be suitable for a sesame allergy. | optional |
soy_allergy | string | Requires that results must be suitable for a soy allergy. | optional |
tree_nut_allergy | string | Requires that results must be suitable for a tree nut allergy. | optional |
wheat_allergy | string | Requires that results must be suitable for a wheat allergy. | optional |
Example allergies parameter:
Substitute Ingredient Conformity
All provided ingredient alternatives will conform to all provided parameters. For example, a vegan alternative for cow’s milk could be Soy Drink, however if both a vegan and soy allergy parameter are provided, an alternative conforming to all provided parameters will be returned, for example Rice Drink.
/api/v1/recipe/profiles/?composition=
The composition parameters accepts multiple arguments and defines which data-points of the included ingredients composition should be returned. Multiple arguments are joined with a comma (' , '). Composition data is returned reflecting the change in overall composition of all included ingredients and as a result of any ingredient substitutions.
Arguments | Type | Description | |
---|---|---|---|
Nutrients | |||
energy | string | Returns overall energy composition change, in kilocalories (Kcal). | optional |
carbohydrate | string | Returns overall carbohydrate composition change, in grams (g). | optional |
sugar | string | Returns overall sugar composition change, in grams (g). | optional |
protein | string | Returns overall protein composition change, in grams (g). | optional |
total_fat | string | Returns overall total fat composition change, in grams (g). | optional |
fibre | string | Returns overall fibre composition change, in grams (g). | optional |
starch | string | Returns overall starch composition change, in grams (g). | optional |
monosach | string | Returns overall monosaccharide composition change, in grams (g). | optional |
disach | string | Returns overall disaccharide composition change, in grams (g). | optional |
saturated_fat | string | Returns overall saturated fat composition change, in grams (g). | optional |
mono_unsaturated_fat | string | Returns overall monounsaturated fat composition change, in grams (g). | optional |
poly_unsaturated_fat | string | Returns overall polyunsaturated fat composition change, in grams (g). | optional |
cholesterol | string | Returns overall cholesterol composition change, in milligrams (mg). | optional |
Minerals | |||
calcium | string | Returns overall calcium composition change, in milligrams (mg). | optional |
iron | string | Returns overall iron composition change, in milligrams (mg). | optional |
magnesium | string | Returns overall magnesium composition change, in milligrams (mg). | optional |
phosphorus | string | Returns overall phosphorus composition change, in milligrams (mg). | optional |
potassium | string | Returns overall potassium composition change, in milligrams (mg). | optional |
sodium | string | Returns overall sodium composition change, in milligrams (mg). | optional |
zinc | string | Returns overall zinc composition change, in milligrams (mg). | optional |
copper | string | Returns overall copper composition change, in milligrams (mg). | optional |
manganese | string | Returns overall manganese composition change, in milligrams (mg). | optional |
selenium | string | Returns overall selenium composition change, in micrograms (µg). | optional |
iodine | string | Returns overall iodine composition change, in micrograms (µg). | optional |
Vitamins | |||
vit_a | string | Returns overall total vitamin A composition change, in international units (iu). | optional |
retinol_vit_a | string | Returns overall retinol (vitamin A) composition change, in micrograms (µg). | optional |
a_carot_vit_a | string | Returns overall alpha carotene (vitamin A) composition change, in micrograms (µg). | optional |
b_carot_vit_a | string | Returns overall beta carotene (vitamin A) composition change, in micrograms (µg). | optional |
b_crypt_vit_a | string | Returns overall beta cryptoxanthin (vitamin A) composition change, in micrograms (µg). | optional |
thiamin_vit_b1 | string | Returns overall thiamin (vitamin B1) composition change, in milligrams (mg). | optional |
riboflavin_vit_b2 | string | Returns overall riboflavin (vitamin B2) composition change, in milligrams (mg). | optional |
niacin_vit_b3 | string | Returns overall niacin (vitamin B3) composition change, in milligrams (mg). | optional |
panto_acid_vit_b5 | string | Returns overall pantothenic acid (vitamin B5) composition change, in milligrams (mg). | optional |
pyridoxin_vit_b6 | string | Returns overall pyridoxine (vitamin B6) composition change, in milligrams (mg). | optional |
vit_b9 | string | Returns overall total vitamin B9 composition change, in micrograms (µg). | optional |
folate_vit_b9 | string | Returns overall folate (vitamin B9) composition change, in micrograms (µg). | optional |
folic_acid_vit_b9 | string | Returns overall folic acid (vitamin B9) composition change, in micrograms (µg). | optional |
cobalamin_vit_b12 | string | Returns overall cobalamin (vitamin B12) composition change, in micrograms (µg). | optional |
ascorbate_vit_c | string | Returns overall ascorbate (vitamin C) composition change, in milligrams (mg). | optional |
vit_d | string | Returns overall total vitamin D composition change, in international units (iu). | optional |
ergocalciferol_vit_d | string | Returns overall ergocalciferol (vitamin D) composition change, in micrograms (µg). | optional |
cholecalciferol_vit_d | string | Returns overall cholecalciferol (vitamin D) composition change, in micrograms (µg). | optional |
vit_e | string | Returns overall total vitamin E composition change, in milligrams (mg). | optional |
a_tocopherol_vit_e | string | Returns overall alpha tocopherol (vitamin E) composition change, in milligrams (mg). | optional |
b_tocopherol_vit_e | string | Returns overall beta tocopherol (vitamin E) composition change, in milligrams (mg). | optional |
g_tocopherol_vit_e | string | Returns overall gamma tocopherol (vitamin E) composition change, in milligrams (mg). | optional |
d_tocopherol_vit_e | string | Returns overall delta tocopherol (vitamin E) composition change, in milligrams (mg). | optional |
vit_k | string | Returns overall total vitamin K composition change, in micrograms (µg). | optional |
phytomenadione_vit_k | string | Returns overall phytomenadione (vitamin K) composition change, in micrograms (µg). | optional |
menaquinone_vit_k | string | Returns overall menuquinone (vitamin K) composition change, in micrograms (µg). | optional |
Example composition parameter:
composition=energy,carbohydrate,protein,total_fat
/api/v1/recipe/profiles/?language=
The default API language can be defined in the BonAPI Account page, meaning all requests with the corresponding token will automatically be analysed in the chosen language. However, a language parameter can be passed to specify the language of the included inputs of a specific API call.
Arguments | Type | Description | |
---|---|---|---|
en | string | Indicates that the request inputs are in english. | optional |
de | string | Indicates that the request inputs are in german. | optional |
Example language parameter:
language=en
/api/v1/recipe/profiles/?match_criteria=
The best ingredient alternatives can be identified through a focus on different elements of the ingredients themselves. This allows for the best match to be determined on a nutrient or mineral content basis for example. By default, all ingredient alternatives are identified on an overall best match level, which takes into account all available data points. Some pillars for identification are still in development and experimental, these are marked with an*.
Arguments | Type | Description | |
---|---|---|---|
overall | string | Find the overall best alternative given the supplied constraints. | default |
nutrients | string | Find the best alternative based on nutrients given the supplied constraints. | optional |
minerals | string | Find the best alternative based on minerals given the supplied constraints. | optional |
vitamins | string | Find the best alternative based on vitamins given the supplied constraints. | optional |
flavor_profile* | string | Find the best alternative based on flavour profile given the supplied constraints. | optional |
structure* | string | Find the best alternative based on structure given the supplied constraints. | optional |
/api/v1/recipe/profiles/?replace_only_unsuitable_ingredients=
By default only ingredients that do not conform to the supplied dietary requirements in diet and allergies with be substituted. However, you can declare that all supplied ingredients should be replaced, regardless of their initial suitability.
Arguments | Type | Description | |
---|---|---|---|
True | string | Only for ingredients that do not adhere to all the provided parameters will ingredient alternative suggestions be provided. | default |
False | string | Ingredient alternative suggestions will be provided for all the ingredients included in the call, regardless if they initially conform to the supplied dietary parameters or not. | optional |
Example Recipe Profiles API
Combining the above examples by creating a JSON format object containing the ingredients and appending the optional parameters in the examples provided joined with ampersand (&) sign to the api endpoint, we come to the below example query.
Example payload to be provided in the API body and in JSON format object
data={"ingredients": ['250gr white wheat flour', '50ml cow milk', '1 chicken breast', '0.5 cups of white rice']}
Example Recipe Profiles API endpoint with parameters:
https://www.bon-api.com/api/v1/recipe/profiles/?composition=energy,carbohydrate,protein,total_fat&language=en
Recipe Profiles API Response
The above example Recipe Profiles API request returns the below response.
JSON Recipe Profiles API response:
Recipe Profiles API response schema
Attribute | Type | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
response_code | number | A JSON response code indicating the succes or reason for failure of the request. | ||||||||||||||||||
request | object | Object containing the received inputs and parameters of the request. Contents include: | ||||||||||||||||||
language | string | Indicates the specified language with which the request was made. | ||||||||||||||||||
provided_ingredients | array | An array containing each element in the ingredients input extracted from its JSON formatting. | ||||||||||||||||||
composition | array | If provided, an array of all composition data points requested for each ingredient (with respect to their quantity). | ||||||||||||||||||
response | object | Object containing the results of the analysis as per the received inputs and parameters of the request. Contents include: | ||||||||||||||||||
alerts | null or object | Alerts will highlight any not understood ingredients, parameters and arguments provided, as well as notifying of any other caught anomalies. If there are no alerts, null is returned. Alerts are only included if an alert is present; possible alerts include:
|
||||||||||||||||||
matched_ingredients | array | An array of all provided ingredients together with an indication of the ingredient to which they were matched in BonAPI's database. Each element is a string containing a provided ingredient, " ---> ". the respective matched ingredient. | ||||||||||||||||||
updated_ingredients | array | An array of all ingredients with cleaned formatting, for example removal of double spacing. | ||||||||||||||||||
diet_1 | array | An array of all diets to which the updated recipe, containing the new ingredient alternatives, could be further constrained to. Returned in the language specified in the request. | ||||||||||||||||||
allergens_1 | array | An array containing all the allergies and intolerances present in the updated recipe, containing the new ingredient alternatives. Returned in the language specified in the request. | ||||||||||||||||||
diet_2 | array | An array of all diets that are offered by BonAPI to constrain a diet to. Returned in the language specified in the request. | ||||||||||||||||||
allergens_2 | array | An array of all allergies and intolerances understood by BonAPI. Returned in the language specified in the request. | ||||||||||||||||||
composition_info | null or object | If no composition data was specified in the composition parameter in the request, this will return null. Otherwise returns an object containing further objects. The first, "overall", contains the composition data of the recipe, as calculated from all the provided ingredient quantities. Following "overall" is then composition data for each data point referenced by their name as stated in the updated_ingredients. Within each object are all specified composition data points as provided in the request. Each compostiion data point is itself an object, referenced by its key (the same as it was called for in the request) and with contents:
|
Response Codes
With each BonAPI request, a JSON response code is returned to indicate the success or reason for failure of the request. Response codes are provided with a detail and description.
{
"response": {
"200 Success": {
"response_code": 200
"detail": "A successful request and response with no identified errors or alerts."
"description": "Indicates that request has succeeded."
},
"400 Bad Request": {
"response_code": 400
"detail": "The criteria: <match_criteria> cannot be used as a match criteria for <ingredient_name>. Please review our documentation and reference APIs."
"description": "The request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications."
},
"401 Unauthorized": {
"response_code": 401
"detail": "Invalid token/Authentication credentials were not provided.",
"description": "Indicates that the request requires user authentication information. The client MAY repeat the request with a suitable Authorization header field."
},
"404 Not Found": {
"response_code": 404
"detail": "The requested resource does not exist.",
"description": "The server can not find the requested resource."
},
"405 Method Not Allowed": {
"response_code": 405
"detail": "The Dynamic Recipe API only accepts POST requests. For further information please check out the documentation page.",
"description": "The request HTTPS method is known by the server but has been disabled and cannot be used for that resource."
},
"426 Upgrade Required": {
"response_code": 426
"detail": "The current plan does not allow the <composition> parameter. Please upgrade to a plan that allows it.",
"description": "The server refuses to perform the request. The server will process the request after the client upgrades to a different protocol."
},
"429 Too Many Requests": {
"response_code": 429
"detail": "Request was throttled. Expected available in x seconds.",
"description": "The user has sent too many requests in a given amount of time."
},
}
}