NAV
shell

API Reference

API Base URI

https://www.wecook.fr/web-api

The WeCook API provides access to resources formatted in JSON.

Authentication

curl "https://www.wecook.fr/web-api/recipes"
  -H "Authorization: Bearer change_with_private_api_token"

Make sure to use your own API token.

To use WeCook, you need to add a Bearer header with your private API token:

Authorization: Bearer change_with_private_api_token

Response

The error case (4xx and 5xx)

{
  "message": "some message describing the error"
}

The non error case (2xx and 3xx)

{
  "result":
}

The WeCook API tries to always send back a JSON object (also called hash). In case of error (HTTP status 4xx and 5xx), the object will contain a message key with a string value describing the error. In case there are no errors (HTTP status 2xx and 3xx), the object will contain a result key of any JSON type as described in the corresponding endpoint documentation.

Versioning

curl "https://www.wecook.fr/web-api/recipes"
  -H "Wecook-Version: 1"

In production, you should use this header.

A custom HTTP header Wecook-Version is used in order to change the API without breaking clients. We do not like breaking things that work, so we try to garantee that a given API version will stay as described in its corresponding documentation document, for as long as possible.

Wecook-Version: 1

The version header works in a stateless manner, which means that we do not link the version you are using to your account. You can use different versions for different endpoints if you wish, so as to be able to update enpoints one by one. Not providing the header is the same as using the latest API version.

Errors

General HTTP Error Status Codes returned by the API:

Error Code Meaning
400 Bad Request – The request is invalid often because of bad formatting or missing parameters.
403 Forbidden – You did not provide an authentication token or the provided token is invalid.
404 Not Found – The specified resource does not exists.
500 Internal Server Error – Something went wrong with our API. We generally do not provide meaningful error message in this case, as the problem comes from our end. Sometimes theses errors are non deterministic (concurrency or latency problems), you can retry your request a few seconds later if you think this is the case.
502 Bad Gateway – API is down often for maintenance reason for a few seconds, you should retry shorly.

Recipes

Search for recipes

curl "https://www.wecook.fr/web-api/recipes/search"
  --get
  -d "q=curry"
  -d "count=2"
  -H "Authorization: Bearer change_with_private_api_token"
  -H "Wecook-Version: 1"

Example response:

{
  "result": {
    "resources": [
      {
        "name": "Curry de Poulet",
        "portions": 2,
        "tags": {
          "meals": [
            "meal_dinner",
            "meal_lunch"
          ],
          "courses": [
            "course_main_dish"
          ]
        },
        "kcal": 781,
        "id": 4178,
        "time": {
          "total": 760
        },
        "wecook_url": "https://www.wecook.fr/recette/curry-de-poulet",
        "picture_url": "https://kiwings-images-prod.s3-eu-west-1.amazonaws.com/recipes/5384545bdeed6.jpeg",
        "ingredients_count": 8
      },
      {
        "name": "Curry japonais",
        "portions": 4,
        "tags": {
          "meals": [
            "meal_dinner",
            "meal_lunch"
          ],
          "courses": [
            "course_main_dish"
          ]
        },
        "kcal": 481,
        "id": 2316,
        "time": {
          "total": 65
        },
        "wecook_url": "https://www.wecook.fr/recette/curry-japonais",
        "picture_url": "https://kiwings-images-prod.s3-eu-west-1.amazonaws.com/recipes/55c0a1ae476ef.jpeg",
        "ingredients_count": 6
      }
    ],
    "metadata": {
      "total_count": 101,
      "current_count": 2,
      "page_number": 1
    }
  }
}

Only retrieve recipes including ingredients 4406 and 2529:

curl "https://www.wecook.fr/web-api/recipes/search"
  --get
  -d "with_is=[4406,2529]"
  -d "count=2"
  -H "Authorization: Bearer change_with_private_api_token"
  -H "Wecook-Version: 1"

Make a Full Text Search of recipes.

To include or exclude ingredients, use an JSON array with ids of the ingredients (example: with_is=[4406,2529]). Ids can be found using the autocomplete api with the query parameter type=ingredient.

A family of ingredients is a concept that represents a set of ingredients, such as fruits. You can search recipes including any ingredients in such families, or without any such ingredients. Use the query parameters with_fs and without_fs. Ids can be found using the autocomplete api with the query parameter type=family.

HTTP Request

GET https://www.wecook.fr/web-api/recipes/search

Query Parameters

Parameter Description
q The search string.
count Number of result by page
default 20
min 1, if below 1 default to 1
max 100, if above 100 default to 100.
page The page of results
default 1
min 1, if below 1 default to 1.
total_time_min Excludes recipes with total time below this (in minutes).
total_time_max Excludes recipes with total time above this (in minutes).
kcal_min Excludes recipes containing less than this number of kilocalories.
kcal_max Excludes recipes containing more than this number of kilocalories.
portions_min Excludes recipes made for a number of people below this.
portions_max Excludes recipes made for a number of people above this.
with_is Only includes recipes containings the ingredients with the ids given in the array.
Example: [4406,2529]
You can find the ids by using the autocomplete api.
without_is Only includes recipes that do not contain the ingredients with the ids given in the array.
with_fs Only includes recipes containings ingredients included in the families with the ids given in the array.
You can find the ids by using the autocomplete api.
without_fs Only includes recipes that do not contain ingredients in the families with the ids given in the array.

Result

result.metadata contains pagination informations:

Key Description
total_count The total number of recipes matching the query.
current_count The number number of recipes in the result.resources array.
page_number The actual position of the result in the complete list of result.
It is often the same number as the query parameter page but can change when out of range.

result.resources is an array of recipe summaries each with the following parameters:

Key Description
id An ID identifying the entity.
name The name of the recipe.
wecook_url The URL of the recipe.
portions Number of people this recipe is made for.
kcal Number of kilocalories in the recipe.
ingredients_count Number of ingredients in the recipe.
picture_url nullable
The URL of the picture of the recipe.
time.total The total time in minutes necessary to make the recipe.
tags.meals array of meal_breakfast, meal_lunch or meal_dinner
Which time of the day (meal) this recipe should be served in preference.
tags.course array of course_entree, course_main_dish or course_dessert
Which order in a given meal (course) this recipe should be served in preference.

Get a Recipe

curl "https://www.wecook.fr/web-api/recipes"
  --get
  -d "id=4975"
  -H "Authorization: Bearer change_with_private_api_token"
  -H "Wecook-Version: 1"

Example response:

{
  "result": [
    {
      "name": "Rôti de porc farci aux oranges et aux figues",
      "portions": 6,
      "tags": {
        "meals": [
          "meal_dinner",
          "meal_lunch"
        ],
        "courses": [
          "course_main_dish"
        ]
      },
      "id": 4975,
      "ingredients": [
        {
          "quantity": 1,
          "unit": "sans unité",
          "name": "rôti de porc"
        },
        {
          "quantity": 2,
          "unit": "gousse",
          "name": "ail"
        },
        {
          "quantity": 300,
          "unit": "gramme",
          "name": "figue"
        },
        {
          "quantity": 2,
          "unit": "sans unité",
          "name": "orange"
        },
        {
          "quantity": 0.5,
          "unit": "sans unité",
          "name": "citron jaune"
        },
        {
          "quantity": 2,
          "unit": "cuillère à soupe",
          "name": "pignon de pin"
        },
        {
          "quantity": 10,
          "unit": "centilitre",
          "name": "porto"
        },
        {
          "quantity": 1,
          "unit": "filet",
          "name": "huile d'olive"
        },
        {
          "quantity": 50,
          "unit": "gramme",
          "name": "beurre"
        },
        {
          "quantity": 1,
          "unit": "cuillère à café",
          "name": "fond de veau"
        },
        {
          "quantity": 5,
          "unit": "gramme",
          "name": "sucre en poudre"
        },
        {
          "quantity": 2,
          "unit": "sans unité",
          "name": "feuille de laurier"
        },
        {
          "quantity": 400,
          "unit": "gramme",
          "name": "riz"
        }
      ],
      "steps": [
        {
          "order": 1,
          "step": "Épluchez l'ail. Pratiquez avec la pointe d'un couteau des incisions dans la viande puis enfoncez-y des éclats d'ail. Frottez-la avec un demi-citron."
        },
        {
          "order": 2,
          "step": "Mettez le rôti dans un plat, assaisonnez-le avec du sel, du poivre, le laurier ciselé et le zeste d'un demi-citron et d'une demi-orange finement râpés. Arrosez-le d'huile."
        },
        {
          "order": 3,
          "step": "Chauffez votre four 210°C. Disposez sur le rôti 30g de beurre en parcelles. Enfournez et laissez cuire 50 minutes en arrosant régulièrement avec le jus de citron."
        },
        {
          "order": 4,
          "step": "Faites cuire le riz dans une fois et demie son volume d'eau bouillante salée."
        },
        {
          "order": 5,
          "step": "Faites caraméliser le sucre à sec dans une petite casserole. Versez le Porto avec précaution et laissez réduire de moitié. Ajoutez le fond de veau et 15cl d'eau et faites frémir 5 minutes. Salez, poivrez, incorporez 20g de beurre. Couvrez d'une feuille d'aluminium et réservez au chaud."
        },
        {
          "order": 6,
          "step": "Disposez les figues rincées et coupées en quatre autour du rôti ainsi que les quartiers d'orange, parsemez de pignons et laissez cuire pendant encore 10 minutes."
        },
        {
          "order": 7,
          "step": "Découpez le rôti, disposez les tranches sur un plat, entourez de figues et de quartiers d'oranges."
        }
      ],
      "time": {
        "total": 75,
        "prep": 15,
        "bake": 60,
        "rest": 0
      },
      "wecook_url": "https://www.wecook.fr/recette/rti-de-porc-farci-aux-oranges-et-au-figues",
      "picture_url": "https://kiwings-images-prod.s3-eu-west-1.amazonaws.com/recipes/521f13b643a46.jpeg",
      "nutrition": {
        "sugar": 6.016670227050781,
        "fiber": 35.06529998779297,
        "sat_fat": 27.771299362182617,
        "protein": 264.0159912109375,
        "kcal": 4448,
        "sodium": 0.029953299090266228,
        "fat": 145.36000061035156,
        "carbo": 516.4110107421875
      }
    }
  ]
}

This endpoint retrieves informations about a specific recipe.

HTTP Request

GET https://www.wecook.fr/web-api/recipes

Query Parameters

Parameter Description
id The ID of the recipe.

Result

result is an array of (zero or one) recipes:

Key Description
id An ID identifying the entity.
name The name of the recipe.
wecook_url The URL of the recipe.
portions Number of people this recipe is made for.
picture_url nullable
The URL of the picture of the recipe.
time.total The total time in minutes necessary to make the recipe.
time.prep nullable
The preparation time in minutes.
time.bake nullable
The baking time in minutes.
time.rest nullable
The resting time in minutes.
tags.meals array of meal_breakfast, meal_lunch or meal_dinner
Which time of the day (meal) this recipe should be served in preference.
tags.course array of course_entree, course_main_dish or course_dessert
Which order in a given meal (course) this recipe should be served in preference.
ingredients array of ingredients.
steps array of steps to make the recipe, order is the order of the step in the list of steps.
nutrition.kcal Number of kilocalories in the recipe.
nutrition.protein Protein quantity in gram.
nutrition.fat Fat quantity in gram.
nutrition.carbo Carbohydrates quantity in gram.
nutrition.sugar Sugar quantity in gram.
nutrition.sat_fat Saturated fat quantity in gram.
nutrition.fiber Fiber quantity in gram.
nutrition.sodium Sodium quantity in gram.

Nutrition results are floats resulting from a computation, they often have 2 significant figures.

Autocomplete

curl "https://www.wecook.fr/web-api/resources/autocomplete"
  --get
  -d "q=sucre"
  -d "type=ingredient"
  -H "Authorization: Bearer change_with_private_api_token"
  -H "Wecook-Version: 1"

Example response:

{
  "result": {
    "ingredient": [
      {
        "name": "sucre en poudre",
        "entity_id": 4406
      },
      {
        "name": "sucre vanillé",
        "entity_id": 5938
      },
      {
        "name": "canne à sucre",
        "entity_id": 5960
      }
    ]
  }
}

Find matches for the text query (autocomplete).

HTTP Request

GET https://www.wecook.fr/web-api/resources/autocomplete

Query Parameters

Parameter Description
q The search string.
type Mandatory
The type of the entities to search
ingredient or family.

Result

result is an object which keys are the type given in parameter (ingredient or family). result.ingredient and result.family are arrays of:

Key Description
name The name of the resource that matches the query.
entity_id The ID of the resource that matches the query.