POST /api/v1/dynamic/recipes

The Dynamic Recipe API is a solution tailored to adjusting ingredients in a recipe to suit given dietary requirements and updating the instructions accordingly to reflect any changes. Both the ingredient list and recipe instructions are required inputs to be provided in the API body as the payload, both are necessary for the analysis that determines which ingredients are most suitable as alternatives. Parameters may also be provided to define the dietary requirements that the recipe 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. Changes in composition data due to ingredient substitutions can be requested with each desired composition type being referenced specifically. The parameter composition is also an optional parameter and can be given multiple arguments. Finally, a language parameter may also be provided to specify the language of the provided ingredients and instructions.

Dynamic Recipe API Request

The Dynamic Recipe API solution also has in it included an ingredient analysis API that is designed to be executed as a set-up on all recipes for which the Dynamic Recipe functionality is desired. This verifies all ingredients are correctly matched (without fully matched ingredients, Dynamic Recipe functionality cannot guarantee the recipe fully complies with any desired dietary restrictions) and also returns the dietary profile of the recipe, including suitable diet and present allergens; this information may be stored and displayed on the recipe page. Below is an overview of the construction a Dynamic Recipe API request with examples provided.

Required Inputs

The Dynamic Recipes API request must contain authorization through the header as well as declaration of the json content type of the payload.

API Headers

Example Header:

{'Authorization': 'Token 1234567890', 'Content-type': 'application/json'}

API Request Body application/json

The payload consists of the ingredients and instructions which are provided in a JSON format object, where the key 'ingredients' contains its value pair as an array containing the ingredients, and the key 'instructions' contains its value pair as an array containing the instrucitons steps.

data={"ingredients": <array of ingredients>, "instructions": <array of instructions>}

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.

Example ingredients array:

['2 tbsp Olive Oil', '4 tbsp Ghee', '0.5 tsp Turmeric', '1 tsp Garam Masala', '0.5 tsp Chili Powder', '1 tsp Pepper', '1.5 tsp Salt', '2 tsp Mustard Seeds', '600 g Onion', '120 g Garlic', '120 g Ginger', '150 g Yoghurt', '1 kg Chicken', 'Coriander for garnish']

data={"ingredients": <array of ingredients>, "instructions": <array of instructions>}

The instructions are provided in the payload of the api body.
Instructions are provided in an array with each element representing a separate step or paragraph in the recipe instructions.

Example instructions array:

['Chop Ginger and Garlic into small dices. Then chop the Onion. The Chicken can be cut into smaller pieces for a shorter cooking time.', 'In a large saucepan or wok, add 2 tablespoons of Ghee and Olive Oil and fry the Mustard seeds on medium heat until they start popping. Add chopped Ginger and Garlic and fry till a golden brown.', 'Add the chopped Onion and let it sauté for approximately 5 minutes.', 'Add in the spices: Turmeric, Garam masala, Chili powder, Coriander powder and Pepper and keep stirring for 30 seconds. Add the Chicken along with 2 more tablespoons of Ghee and let it fry for 10 minutes while stirring on high fire.', 'Add in the Yoghurt and stir well on medium fire until it starts boiling. At this point reduce the heat to low and let it simmer until the sauce has thickened up.', 'Garnish with fresh Coriander and enjoy!']

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/dynamic/recipes/?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.

Example diet parameter:

diet=vegetarian

/api/v1/dynamic/recipes/?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.

Example allergies parameter:

allergies=gluten_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/dynamic/recipes/?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.

Example composition parameter:

composition=energy,fibre,calcium,iron,cobalamin_vit_b12,ascorbate_vit_c

/api/v1/dynamic/recipes/?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.

Example nutrition_claims parameter:

nutrition_claims=true

/api/v1/dynamic/recipes/?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.

Example seasonality parameter:

seasonality=eur

/api/v1/dynamic/recipes/?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.

Example language parameter:

language=en

/api/v1/dynamic/recipes/?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*.

/api/v1/dynamic/recipes/?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.

Example Dynamic Recipe API

Combining the above examples by creating a JSON format object containing the ingredients and instructions 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": ['2 tbsp Olive Oil', '4 tbsp Ghee', '0.5 tsp Turmeric', '1 tsp Garam Masala', '0.5 tsp Chili Powder', '1 tsp Pepper', '1.5 tsp Salt', '2 tsp Mustard Seeds', '600 g Onion', '120 g Garlic', '120 g Ginger', '150 g Yoghurt', '1 kg Chicken', 'Coriander for garnish'], "instructions": ['Chop Ginger and Garlic into small dices. Then chop the Onion. The Chicken can be cut into smaller pieces for a shorter cooking time.', 'In a large saucepan or wok, add 2 tablespoons of Ghee and Olive Oil and fry the Mustard seeds on medium heat until they start popping. Add chopped Ginger and Garlic and fry till a golden brown.', 'Add the chopped Onion and let it sauté for approximately 5 minutes.', 'Add in the spices: Turmeric, Garam masala, Chili powder, Coriander powder and Pepper and keep stirring for 30 seconds. Add the Chicken along with 2 more tablespoons of Ghee and let it fry for 10 minutes while stirring on high fire.', 'Add in the Yoghurt and stir well on medium fire until it starts boiling. At this point reduce the heat to low and let it simmer until the sauce has thickened up.', 'Garnish with fresh Coriander and enjoy!']}

Example Dynamic Recipe API endpoint with parameters:

https://www.bon-api.com/api/v1/dynamic/recipes/?diet=vegetarian&allergies=gluten_allergy,lactose_intolerance&composition=energy,fibre,calcium,iron,cobalamin_vit_b12,ascorbate_vit_c&language=en

Dynamic Recipe API Response

The above example Dynamic Recipe API request returns the below response.

JSON Dynamic Recipe API response:

Dynamic Recipe API response schema

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