Alacalc API documentation

This document provides API information for connecting to the Alacalc Nutritional Information system.

In order to use this API, you need to create an API key from your user account.

Example usage

Creating a new session

The first step is to to authenticate and store the session information in a cookie. Once you have obtained the login-email and the API key from your account, the session is created with:

curl -c alacalc_cookie --data "[email protected]&api_access_key=APIKEY"

Obtain list of all recipes

We can use the API to retrieve information from the alacalc system. For example to obtain a list of all recipes, we use:

curl -b alacalc_cookie

Retrieve allergen and nutritional information of a recipe

We can retrieve the allergen and nutritional information of the recipe with id=123 with:

curl -b alacalc_cookie ",nutrition"

Download a food label

Finally, we can download the food label with

curl -b alacalc_cookie -o label.svg ""

Create a new recipe

A new recipe is created by making a post request, for instance with

curl --header "Content-Type: application/json" --request POST -b alacalc_cookie --data '{"recipes":{"name":"My new recipe","quantity_per_serving":100,"weight_loss":0}}'

Create a new user

A new user can be created with:

curl --header "Content-Type: application/json" --request POST --data '{"email":"[email protected]","password":"mysecret"}'

The return value contains the user's API key, which can be used to create a new user sessions.

Update a user

The information of a user can be updated with (note that you need a session cookie here):

curl --header "Content-Type: application/json" --request PUT -b alacalc_cookie --data '{"firstname":"Simon"}'


Ingredient items

Resource Description
GET /api/v1/recipes/:recipe_id/ingredient_items Show a recipe's ingredient items
POST /api/v1/recipes/:recipe_id/ingredient_items Add an ingredient items to a recipe
PUT /api/v1/recipes/:recipe_id/ingredient_items/:id Update an ingredient items associated with a recipe
DELETE /api/v1/recipes/:recipe_id/ingredient_items/:id Delete an ingredient items associated with a recipe


Resource Description
GET /api/v1/ingredients/:id Show an ingredient
POST /api/v1/ingredients Create an ingredient
PUT /api/v1/ingredients Update a recipe
GET /api/v1/ingredients/search Search ingredients


Resource Description
GET /api/v1/recipes List recipes (most recent first)
GET /api/v1/recipes/:id Show a recipe
GET /api/v1/recipes/:id/allergens Deprecated: use recipes/:id?include=allergens instead.
GET /api/v1/recipes/:id/label.[:format] Get a label
GET /api/v1/recipes/:id/declaration_names Get the declaration names as HTML. <br> This will return a string formatted with HTML tags for the ingredients declaration for the subject recipe. The formatting adheres to the following rules: <ul> <li>Uses the ingredient declaration names defined for each ingredient</li> <li>Ingredients are ordered by their weight proportion (descending)</li> <li>Ingredients are comma separated</li> <li>Allergens are tagged with &lt;b&gt; tags in brackets after the name of the ingredient, unless the name of the ingredient is equal to the allergen name</li> <li>Component ingredients are listed in brackets after the name of the component</li> <li>Component ingredients lists follow the above rules</li> </ul> This formatted output can be used directly as the ingredients declaration and is compliant with UK/EU retail packaging regulations.
POST /api/v1/recipes Create a recipe
PUT /api/v1/recipes/:id Update a recipe
PUT /api/v1/recipes/parse Parse a recipe from a string


Resource Description
POST /api/v1/sessions Create a user session using a POST request (recommended)
GET /api/v1/sessions/create_via_get Create a user session with a GET request (mostly for auto-login purposes)
DELETE /api/v1/sessions Destroys a user session


Resource Description
POST /api/v1/users Create a user (optionally associated with a parent account) and returns the user's API key.
PUT /api/v1/users Update the user information.
GET /api/v1/users/show_usage Gives an overview of the account usage (e.g. number and detailed information about the created recipes during the period) over a specific time-period. If the account is a parent account then same summary is given for all child accounts.