NAV
shell

API Reference

API Base URI

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

The WeCook API provides access to resources formatted in JSON.

Authentication

curl "https://www.wecook.fr/recipe/web-api/v2/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

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.
401 Unauthorized – You did not provide an authentication token.
404 Not Found – The specified resource does not exists.
500 Internal Server Error – Something went wrong with our API.
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/recipe/web-api/v2/recipes/search?q='riz'"
  -H "Authorization: Bearer change_with_private_api_token"

Example response:

{
  "result": {
    "resources": [
      {
      "uri": riz-cantonnais-facile,
        "name": "Riz cantonnais facile",
        "wecook_url": "https://www.wecook.fr/recette/riz-cantonnais-facile",
        "portions": 4,
        "kcal": 950,
        "ingredients_count": 10,
        "picture_url": "https://kiwings-images-prod.s3-eu-west-1.amazonaws.com/recipes/521f132a9e765.jpeg",
        "time": {
          "total": 50
        },
        "tags": {
          "meals": ["meal_dinner", "meal_lunch"],
          "course": ["course_main_dish"]
        }
      },
      {
        "uri": boeuf-au-paprika-riz,
        "name": "Boeuf au paprika, riz",
        "wecook_url": "https://www.wecook.fr/recette/boeuf-au-paprika-riz",
        "portions": 4,
        "kcal": 1584,
        "ingredients_count": 8,
        "picture_url": "https://kiwings-images-prod.s3-eu-west-1.amazonaws.com/recipes/52a6e6e42425b.jpeg",
        "time": {
          "total": 35
        },
        "tags": {
          "meals": ["meal_dinner", "meal_lunch"],
          "course": ["course_main_dish"]
        }
      }
    ],
    "metadata": {
      "total_count": 765,
      "current_count": 20,
      "page_number": 1
    }
  }
}

Only retrieve recipes including ingredients foodOignon__cuit and foodVeau__roti:

curl "https://www.wecook.fr/recipe/web-api/v2/recipes/search"
  --get
  -d "with_is=[foodOignon__cuit,foodVeau__roti]"
  -H "Authorization: Bearer change_with_private_api_token"

Make a Full Text Search of recipes.

To include or exclude ingredients, use an JSON array with uris of the ingredients (example: with_is=[foodOignon__cuit,foodVeau__roti]). Uris 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. Uris can be found using the autocomplete api with the query parameter type=family.

HTTP Request

GET https://www.wecook.fr/recipe/web-api/v2/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 uris given in the array.
Example: [foodOignon__cuit,foodVeau__roti]
You can find the uris by using the autocomplete api.
without_is Only includes recipes that do not contain the ingredients with the uris given in the array.
with_fs Only includes recipes containings ingredients included in the families with the uris given in the array.
You can find the uris by using the autocomplete api.
without_fs Only includes recipes that do not contain ingredients in the families with the uris 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
uri An uri 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/recipe/web-api/v2/recipes"
  --get
  -d "uri=cake-au-saumon-fume-et-citron"
  -H "Authrization: Bearer change_with_private_api_token"

Example response:

{
  "result": [
    {
      "uri": cake-au-saumon-fume-et-citron,
      "name": "Cake au saumon fumé et citron",
      "wecook_url": "https://www.wecook.fr/recette/cake-au-saumon-fume-et-citron",
      "portions": 6,
      "picture_url": "https://kiwings-images-prod.s3-eu-west-1.amazonaws.com/recipes/521f11245c8ae.jpeg",
      "time": {
        "total": 10,
        "prep": 15,
        "bake": 45,
        "rest": 0
      },
      "tags": {
        "meals": ["meal_dinner", "meal_lunch"],
        "course": ["course_entree"]
      },
      "ingredients": [
        {
          "quantity": 4,
          "unit": "tranche",
          "name": "Saumon fumé"
        },
        {
          "quantity": 10,
          "unit": "centilitre",
          "name": "Huile d'olive vierge"
        },
        {
          "quantity": 3,
          "unit": "sans unité",
          "name": "Oeuf"
        }
      ],
      "steps":[
        {
          "order": 1,
          "step": "Préchauffez le four à 190°C."
        },
        {
          "order": 2,
          "step": "Dans un saladier, mélangez les œufs, la farine, la levure, l'huile d'olive et la crème fraîche jusqu'à l'obtention d'un mélange crémeux."
        },
        {
          "order": 3,
          "step": "Ajoutez le jus de citron puis fouettez le mélange."
        },
        {
          "order": 4,
          "step": "Incorporez le gruyère, le saumon fumé coupé en morceaux et la ciboulette ciselée. Salez et poivrez au moulin."
        },
        {
          "order": 5,
          "step": "Versez la préparation dans un moule à cake préalablement beurré et enfournez pour 45 minutes."
        }
      ],
      "nutrition": {
        "kcal": 2498.09,
        "protein": 89.8465,
        "fat": 184.23865,
        "carbo": 112.948,
        "sugar": 8.51775,
        "sat_fat": 58.3942,
        "fiber": 7.4655,
        "sodium": 1.757345
      }
    }
  ]
}

This endpoint retrieves informations about a specific recipe.

HTTP Request

GET https://www.wecook.fr/recipe/web-api/v2/recipes?uri=<recipe uri>

Query Parameters

Parameter Description
uri The URI of the recipe.

Result

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

Key Description
ur An URI 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/recipe/web-api/v2/resources/autocomplete"
  --get
  -d "q=oi"
  -d "type=ingredient"
  -H "Authorization: Bearer change_with_private_api_token"

Example response:

{
  "result": {
    "ingredient": [
      {
        "name": "Oignon",
        "uri": foodOignon__cru
      },
      {
        "name": "Oie rôtie",
        "uri": foodOie__viande__rotie
      }
    ]
  }
}

Find matches for the text query (autocomplete).

HTTP Request

GET https://www.wecook.fr/recipe/web-api/v2/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.
uri The URI of the resource that matches the query.