preloading the font
BonAPI | Ingredient Alternatives API Documentation
BonAPI-logo

INGREDIENT ALTERNATIVES API DOCUMENTATION

Page Overview

POST /api/v1/ingredient/alternatives

The Ingredient Alternatives API is a solution tailored to offering ingredient substitutions to suit given dietary requirements. Only an ingredient list in the form of a JSON array is a required element to be provided in the API body as the payload. Parameters may also be provided to define the dietary requirements that the ingredients should be made to conform to: these include both a diet and an allergies parameter. Diet can be defined in a single argument, while allergies may be given multiple arguments. Composition data can be requested with each desired composition type being referenced specifically. The parameter composition is also an optional parameter and can be given multiple values. Finally, a language parameter may also be provided to specify the language of the provided ingredients.

Ingredient Alternatives API Request

Below is an overview of the construction a Ingredient Alternatives API request with examples provided.

Required Inputs

The Ingredient Alternatives 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 the 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

Different parameters can be provided to define the dietary requirements the ingredients should be made to conform to.
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/ingredient/alternatives/?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:
diet=vegetarian

/api/v1/ingredient/alternatives/?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:
allergies=soy_allergy,lactose_intolerance

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/ingredient/alternatives/?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=total_fat,sugar,protein,calcium,water_content

/api/v1/ingredient/alternatives/?nutrition_claims=

The nutrition_claims parameter accepts one argument and defines whether any relevant nutrition claims should be returned.
The nutrition claims are provided as defined by the European Commission here. Claims are returned in the request defined language and relate only to the ingredients which have an understood quantity, i.e. do not appear in the null_composition list in the alerts section of the response-see the schema below for more details.

Arguments Type Description
true string Triggers any relevant nutrition claims be returned. optional
false string Default. Triggers no nutrition claims be returned. optional
Example nutrition_claims parameter:
nutrition_claims=true

/api/v1/ingredient/alternatives/?seasonality=

The seasonality parameter accepts one argument and defines the region for which seasonality information for the provided ingredients should be returned.
Only a list of the ingredients that are currently in season in the given region are returned - the rest can be assumed to not be in season.

Arguments Type Description
false string Default. No seasonality information is requested. optional
eur string Definition that any ingredients currently in season in Europe be returned as in season. optional
Example seasonality parameter:
seasonality=eur

/api/v1/ingredient/alternatives?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. Support for some languages is still in development and experimental, these are marked with*.

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
nl string Indicates that the request inputs are in dutch.* optional
fr string Indicates that the request inputs are in french.* optional
es string Indicates that the request inputs are in spanish.* optional
it string Indicates that the request inputs are in italian.* optional
lv string Indicates that the request inputs are in latvian.* optional
Example language parameter:
language=en

/api/v1/ingredient/alternatives/?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/ingredient/alternatives/?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 Ingredient Alternatives 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 Ingredient Alternatives API endpoint with parameters:
https://www.bon-api.com/api/v1/ingredient/alternatives/?diet=vegetarian&allergies=soy_allergy,lactose_intolerance&composition=total_fat,sugar,protein,calcium,water_content&language=en

Ingredient Alternatives API Response

The above example Ingredient Alternatives API request returns the below response.

JSON Ingredient Alternatives API response:

Ingredient Alternatives API response schema

Attribute Type Description
response_code number A JSON response code indicating the success 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.
diet string If provided, the specified diet to which all returned ingredient alternatives should conform to.
allergies array If provided, an array of allergies and intolerances which all returned ingredient alternatives should be suitable for.
composition array If provided, an array of all composition data points requested for each ingredient (with respect to their quantity).
nutrition_claims string If provided, a string indicating 'true' should the request return any nutrition claims as defined by the European Commission (https://ec.europa.eu/food/safety/labelling_nutrition/claims/nutrition_claims_en).
seasonality array If provided, the region for which to return any ingredients which are currently in season. Otherwise the default is "false".
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:
Alert Type Description
ingredients_not_found array Contains all provided ingredients that were not matched to any internal ingredient and thereby not found. This is present in conjunction with a 404 response code.
na_composition array Contains a list of all provided ingredients for which no quantity was deduced, making it not possible to return composition information for them. These ingredients' composition information are also not included in the overall composition values.
null_composition null or object Returns an object that lists any requested composition data-points per ingredient that do not have a defined value in our database (null) and are therefore not included in the calculation of the overall composition values. If all requested data-points are present for all ingredients, this will not be shown or return null.
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 all unsuitable ingredients, as specified by the provided arguments within the parameters of diet and allergies, now replaced by suitable ingredient alternatives. All quantities are also provided for the new ingredients.
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 "overall" contains the composition data of the recipe, as calculated from all the provided ingredient quantities. This has contents:
Attribute Type Description
name string The name of the given composition data point. Returned in the language specified in the request.
unit string The unit of the given composition data point.
value number A decimal value of the given composition data point contained in the "overall" or specific ingredient given the provided quantities.
nutrition_claims array An array of all nutrition claims that could be made regarding the recipe as defined by the European Commission (https://ec.europa.eu/food/safety/labelling_nutrition/claims/nutrition_claims_en), taking into account all fully understood ingredients; i.e. not including any specified in the 'na_composition' in alerts. Nutritional claims are given in the language specified in the request.
seasonality array An array of all ingredients among those included in the request that are currently in season in the provided region.

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."
        },
    }
}