POST /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

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.

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/?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,carbohydrate,protein,total_fat

/api/v1/recipe/profiles/?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/recipe/profiles/?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/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.

Example language parameter:

language=en

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

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