preloading the font
BonAPI | API Documentation

Getting started

API Access Token

Your API Access Token is your unique authentication key to access the BonAPI. Upon signup, you will find it in your account page.

In general, there are two support APIs and the Alternatives API that can be accessed. The first is the Profiles BonAPI that returns a list of all available ingredients for replacement together with an overview of each ingredient and the data types available. The second, the Parameters BonAPI gives a list of all tags that can be passed through as parameters or to call specific composition data if in an appropriate plan. Finally, the Alternatives BonAPI returns the ingredient specific alternatives and requested data types. All plans come with support for 256-bit SSL encryption. To connect via the SSL encryption, simply use the https protocol.

Support APIs

Profiles BonAPI

The first reference API for the Alternatives BonAPI, this gives an overview of all ingredients and their respective parameters and composition data available.
Below you can find an excerpt of the Profiles BonAPI response:



Parameters BonAPI:

The second reference API for the Alternatives BonAPI, the Parameters BonAPI can be used as a guide as it shows the available optional inputs that can be included in a query for alternatives of an ingredient given its availability shown in the Profiles BonAPI. Availability of ingredients in languages other than English may be limited.
Below is the output of the Parameters BonAPI illustrating all optional inputs that can be included to refine the search for suitable alternatives:



Dynamic Ingredients API

Below you can find an example of the Dynamic Ingredients API response. Here, the query looks for alternatives to 4 different ingredients—white rice, wheat flour, cow milk, chicken breast—while setting parameters of a gluten allergy, lactose intolerance and a vegan diet. Note that alternative suggestions are only offered for those ingredients that do not adhere to the parameters provided. For the ingredient alternative suggestions, the following composition data is requested: total fat, sugar, protein, calcium, iron, vitamin B9, vitamin B12 and water content.

URL: white wheat flour,50ml cow milk,1 chicken breast,0.5 cups white rice/?allergies=gluten_allergy,lactose_intolerance&diet=vegan&composition=total_fat,sugar,protein,calcium,iron,vit_b9,cobalamin_vit_b12,water_content


Dynamic Recipe API

Below you can find an example of the Dynamic Recipe API response. Here, the recipe is being made vegetarian and suitable for a lactose intolerance. Note that there is an un-matched ingredient, 'Raindrops', which is then clearly shown in the response under the alerts. BonAPI has a Recipe Profile API that should be run prior to the Dynamic Recipe API as it outlines which ingredients are matched in our database and therefore can act as a gatekeeper to offering the Dynamic Recipe API at all—refer to the Demo for a live example.

URL: tbsp Olive Oil,4 tbsp Ghee,0.5 tsp Turmeric,1 tsp Garam Masala,0.5 tsp Chili Powder,1 tsp Raindrops,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/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ée 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!/?diet=vegetarian&allergies=lactose_intolerance


Error Codes

Whenever a resource is unavailable or the BonAPI call fails for another reason, a JSON error is returned. Error messages will always come with a status code and a description.
Below you find an overview of the errors returned by faulty requests::

    "error": {
        "400 Bad Request": {
            "status_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 you made was invalid"
        "401 Unauthorized": {
            "status_code": 401
            "detail": "Invalid token/Authentication credentials were not provided.",
            "description": "If accessing through URL, please SIGN IN to your account on BonAPI. Otherwise please attach a valid BonAPI token to your request and try again."
        "404 Not Found": {
            "status_code": 404
            "detail": "The requested resource does not exist.",
            "description": "The requested ingredient does not exist in our database or we do not have it in the language you have searched for it in. Check the Ingredient Profiles API for all available ingredients."
        "405 Method Not Allowed": {
            "status_code": 405
            "detail": "The Dynamic Recipe API only accepts POST requests. For further information please check out the documentation page.",
            "description": "You used the wrong method to access this API"
        "426 Upgrade Required": {
            "status_code": 426
            "detail": "The current plan does not allow the <composition> parameter. Please upgrade to a plan that allows it.",
            "description": "You need to upgrade your plan to access this resource"
        "429 Too Many Requests": {
            "status_code": 429
            "detail": "Request was throttled. Expected available in x seconds.",
            "description": "You have exceeded your daily request amount. Try again tomorrow or upgrade plans."
Sample Code

Below you can find code samples to integrate the BonAPIs into your project. In case of the Dynamic Recipe API, please make a POST request:


url = '<ingredients>/'
response = requests.get(url, headers={'Authorization': 'Token {}'.format(<your_bonapi_token>)})


curl<ingredients>/ -H 'Authorization: Token <your_bonapi_token>'


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "<ingredients>/",
    "Authorization: Token <your_bonapi_token>"

$response = curl_exec($curl);

echo $response;

Node.js - Request:

var request = require('request');
var options = {
  'method': 'GET',
  'url': '<ingredients>/',
  'headers': {
    'Authorization': 'Token <your_bonapi_token>'
  formData: {

request(options, function (error, response) { 
  if (error) throw new Error(error);

C# - RestSharp:

var client = new RestClient("<ingredients>/");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Token <your_bonapi_token>");
IRestResponse response = client.Execute(request);