1. General Usage

The Recipe API is structured as a REST service. This means using the HTTP protocol and the HTTP verbs (GET, POST, PUT, etc) to interact with the resources.

1.1. Authentication

For most Recipe API services authentication is needed. To authenticate, send an API key in the x-api-key header for every service call.

For example, to retrieve the recipe with id 12:

curl    -H "x-api-key:30b02a312a4f9630c3f35cceed0826a4" \
        "http://receptenapi-restapi.boodschappen.nl/v1/recipes/12"

1.2. Response Format

To specify the response format, the Recipe API supports the following Accept headers:

'Accept' Header Response Format

application/json

JSON (default)

application/xml

XML
For the best response times, use JSON as the response format.

1.3. Example

To retrieve recipe 12 in XML format:

curl    -H "x-api-key: 30b02a312a4f9630c3f35cceed0826a4" \
        -H "Accept: application/xml" \
        "http://receptenapi-restapi.boodschappen.nl/v1/recipes/12"

1.4. Request Format

To specify the request format, the Recipe API supports the following Content-Type headers:

'Content-Type' Header Request Format

application/x-www-form-urlencoded

URL-encoded (default)

application/json

JSON

application/xml

XML
All examples in this manual use JSON as the request and response formats.

1.5. Example

To search for recipes containing the word "banaan" and have the API return facets, use either URL encoding:

curl    -H "x-api-key: 30b02a312a4f9630c3f35cceed0826a4" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -X POST \
        -d "full_text=banaan&return_facets=true" \
        "http://receptenapi-restapi.boodschappen.nl/v1/recipes/search"

or JSON encoding:

curl    -H "x-api-key: 30b02a312a4f9630c3f35cceed0826a4" \
        -H "Content-Type: application/json" \
        -X POST \
        -d '{"full_text":"banaan", "return_facets":"true"}' \
        "http://receptenapi-restapi.boodschappen.nl/v1/recipes/search"

or XML encoding:

curl    -H "x-api-key: 30b02a312a4f9630c3f35cceed0826a4" \
        -H "Content-Type: application/xml" \
        -H "Accept: application/xml" \
        -X POST \
        -d "<root><full_text>banaan</full_text><return_facets>true</return_facets></root>" \
        "http://receptenapi-restapi.boodschappen.nl/v1/recipes/search"

1.6. Status Codes

The Recipe API uses HTTP response status codes to indicate if the call was successful or if an error occurred. Below is a table of the most common status codes that the Recipe API uses.

Status Code Description

200 OK

The call has succeeded.

400 Bad Request

The request could not be parsed correctly.
For example: incorrect JSON or XML was provided.

403 Forbidden

The call was unauthorized.
For example: incorrect or missing API key.

404 Not Found

A requested entity was not found.

422 UnprocessableEntity

The request was parsed correctly but contained incorrect data.
For example: a required field was missing.

500 InternalServiceError

The server encountered an unexpected condition which prevented it from fulfilling the request.

2. Identifying Recipes

Recipes can be uniquely identified by id and by slug. Every API call that accepts a recipe id also accepts a recipe slug.

For example, both these queries retrieve the same recipe (92 - Beef Wellington):

  1. GET /v1/recipes/92

  2. GET /v1/recipes/beef-wellington

3. Retrieving a Single Recipe

To retrieve a single recipe based on the recipe id or slug, use the following call:

GET /v1/recipes/{id}

A recipe entity always contains all of the fields below, but most recipes do not have data for every field. Fields that do not have data contain either a null value or an empty array.

The table below describes the data structure of a recipe entity.

(*) Field cannot be null.

Field Type Description

id

number (*)

Unique id of the recipe.

slug

string (*)

Unique short name of the recipe.

canonical_url

string (*)

URL where the original "canonical" recipe can be found.

created

datetime (*)

Recipe create date

updated

datetime (*)

Recipe last update date

title

string (*)

Recipe title.

subtitle

string

Recipe subtitle.

preparation_time

number (*)

Recipe total preparation time in minutes.

kcal

number

Recipe amount of kilocalories per person.

fat

number

Recipe amount of fats in grams per person.

saturated_fat

number

Recipe amount of saturated fats in grams per person.

carbs

number

Recipe amount of carbohydrates in grams per person.

protein

number

Recipe amount of proteins in grams per person.

fibers

number

Recipe amount of fibers in grams per person.

salt

number

Recipe amount of salt in grams per person.

prepreparation

string

Recipe prepreparation instructions.

preparation

string

Recipe preparation instructions.

persons

number

Recipe serving size in number of persons.

pieces

number

Recipe serving size in number of pieces.

variation

string

Recipe variation instructions.

wine_advice

string

Recipe wine advices.

status

object (*)

Recipe status.

difficulty

object (*)

Recipe difficulty.

images

object array

Recipe images.

kitchens

object array

Recipe cuisines (French, Asian, etc.)

courses

object array

Recipe courses (breakfast, dinner, etc.)

requirements

object array

Recipe requirements (kitchen utensils, etc.)

ingredients

object array

Recipe ingredients.

times

object array

Recipe individual cooking times.

steps

object array

Recipe preparation instructions.

tags

object array

Recipe tags.

tips

object array

Recipe tips.

wines

object array

Recipe wine advices.

magazines

object array

Magazine issues the recipe was published in.

menus

object array

Menus in which the recipe is included.

rating

object (*)

Recipe rating.

views

object (*)

Recipe view count.

4. Retrieving Images

Recipes can have multiple associated images each with a unique id. To download a full-size image, use the following API call:

GET /v1/download/image/{id}

Download API calls are different from the other API calls in that:

  1. The response contains the binary data of the downloaded image.

  2. They don’t require authorization.

This makes it possible to use the download URL in an <img> HTML tag:

<img src="http://receptenapi-restapi.boodschappen.nl/v1/download/image/1293" />

4.1. Image Variants

The full-size images are the raw source images, so they don’t have a fixed resolution or aspect ratio. An image has one or more variants. A variant is a crop of an image with a fixed aspect ratio and size.

See the appendix for the available variants. An image may not have all the available variants. What variants are available for a specific image depends on the source image size.

Each variant has a unique name. To download a variant for an image, use the following API call:

GET /v1/download/image/{id}/{variant_name}

For example, to download the low quality 2:1 aspect ratio variant of the image with id 1293, use the following API call:

GET /v1/download/image/1293/low-780x390-ratio-2x1

5. Searching Recipes

To search for recipes, use the following API call:

POST /v1/recipes/search

The default search with no parameters returns all recipes that have status active, sorted by relevance.

5.1. Pagination

By default, the search call returns 15 recipes per page. Use the items_per_page parameter to set the number of recipes the search call should return per page and the page parameter to set the page to return. (starting at 0).

To retrieve page 2 of the result set with 20 items per page, use the following API request:

{
  "items_per_page": 20,
  "page": 2
}

The response has a header element that contains the total pages in the result set and the total items in the resultset.

{
  "header": {
    "page": 2,
    "total_pages": 100,
    "items_per_page": 20,
    "total_items": 1982
  },
  ...
}

5.2. Filtering

The search call supports a number of parameters that can be used to filter the result set. These filter parameters can be categorized based on their suffix.

For example, to search for recipes that have the following characteristics:

  1. Have the word "courgette" in the recipe text.

  2. Can be made in 20 minutes or less.

  3. Are of easy difficulty.

the following request can be used:

{
  "full_text": "courgette",
  "preparation_time_int": "[0 TO 20]",
  "difficulty_str": "eenvoudig"
}

The appendix lists the available filters.

The recipe search functionality is backed by the Apache Solr search platform, so a lot of the advanced features of Solr can also be used when searching recipes.

5.2.1. Escaping Special Characters

When using the following special characters in a literal string, they must either be escaped or the string must be quoted:

+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ <space>

So when using a literal string like "moment/in de pauze (snack)" in a query, it should either be escaped:

{
    "full_text": "banaan",
    "tag_multi_str": "moment/in\ de\ pauze\ \(snack\)"
}

or quoted:

{
    "full_text": "banaan",
    "tag_multi_str": "\"moment/in de pauze (snack)\""
}

5.2.2. Text Parameters

Parameters with the _text suffix are used to search in the recipe text fields like title, subtitle, preparation and ingredient fields.

Example queries using the full_text parameter:

  1. Find recipes with "courgette" in the text:
    courgette

  2. Find recipes with "courgette" and "tomaat" in the text:
    courgette AND tomaat

  3. Find recipes with "courgette" or "aubergine" in the text:
    courgette OR aubergine

  4. Find recipes with "gele rijst" and "feta" in the text:
    "gele rijst" AND feta

Use quotes when searching for a phrase with spaces like "gele rijst". Otherwise the search will return all recipes with either "gele" or "rijst" in the text.

5.2.3. Int Parameters

Parameters with the _int suffix are used to search in numeric fields.

Example queries using the fat_int parameter:

  1. Find recipes with exactly 20 grams of fat:
    20

  2. Find recipes with 15 grams of fat or less:
    [0 TO 15]

  3. Find recipes with at least 15 grams of fat:
    [15 TO *]

5.2.4. Date Parameters

Parameters with the _date suffix are used to search in date fields.

Example queries using the updated_date parameter:

  1. Find recipes updated between 2010-01-01 and 2015-01-01:
    ["2010-01-01T00:00:00Z" TO "2015-01-01T00:00:00Z"]

  2. Find recipes updated since 2010-01-01:
    ["2010-01-01T00:00:00Z" TO NOW]

  3. Find recipes updated in the last two weeks:
    [NOW-14DAYS TO NOW]

Dates must be in Complete ISO 8601 format and they must be escaped/quoted (since the colon is a special character).

5.2.5. Id Parameters

Parameters with the _id suffix are used to search in one-to-one relations using the id.

Example queries using the difficulty_id parameter:

  1. Find recipes with difficulty 1 (eenvoudig):
    1

  2. Find recipes with difficulty 2 (gemiddeld) or 3 (moeilijk):
    2 OR 3

5.2.6. String Parameters

Parameters with the _str suffix are used to search in one-to-one relations using the string representation.

Example queries using the difficulty_str parameter:

  1. Find recipes with difficulty "eenvoudig":
    eenvoudig

  2. Find recipes with difficulty "gemiddeld" or "moeilijk":
    eenvoudig OR moeilijk

String parameters are typically used in facetted searches.

5.2.7. Multi-id Parameters

Parameters with the _multi_id suffix are used to search in one-to-many relations using the id’s.

Example queries using the tag_multi_id parameter:

  1. Find recipes with tag 10 (vegetarisch):
    10

  2. Find recipes with tag 10 (vegetarisch) or tag 79 (veganistisch):
    10 OR 79

  3. Find recipes with tag 10 (vegetarisch) and tag 4 (zonder noten):
    10 AND 4

  4. Find recipes with tag 10 (vegetarisch) or tag 79 (veganistisch), and tag 4 (zonder noten):
    (10 OR 79) AND 4

5.2.8. Multi-string Parameters

Parameters with the _multi_str suffix are used to search in one-to-many relations using the string representations.

Example queries using the tag_multi_str parameter:

  1. Find recipes with tag "vegetarisch":
    "type gerecht/vegetarisch"

  2. Find recipes with tag "vegetarisch" or tag "veganistisch":
    "type gerecht/vegetarisch" OR "type gerecht/veganistisch"

  3. Find recipes with tag "vegetarisch" and tag "zonder noten":
    "type gerecht/vegetarisch" AND "dieet en allergieën/zonder noten"

  4. Find recipes with tag "vegetarisch" or tag "veganistisch", and tag "zonder noten":
    ("type gerecht/vegetarisch" OR "type gerecht/veganistisch") AND "dieet en allergieën/zonder noten"

Multi-string parameters are typically used in facetted searches.

5.3. Sorting

By default, results are sorted descending by relevance. Use the sort_fields parameter to provide a custom sort order.

For example, to sort recipes by preparation time and then by updated date, use the following request:

{
    "sort_fields": "preparation_time_int asc, updated_date desc",
    "full_text": "banaan"
}

It is not possible to sort on multi or text fields.

5.4. Facetting

To have the search return facets, set the return_facets parameter to true:

{
    "return_facets", "true",
    "full_text": "banaan"
}

If no other facet parameters are set, the search API returns a default set of facets.

There are two types of facets: value facets and range facets.

5.4.1. Value Facets

The search response below shows the course_multi_str value facets:

{
  "header": ...,
  "results": ...,
  "facets": {
    "course_multi_str": [
      "bijgerecht|290",
      "brunch|64",
      "hoofdgerecht|1041",
      "klein gerecht|46",
      "klein gerecht/amuse|9",
      "klein gerecht/hapje|103",
      "klein gerecht/snack|73",
      "lunch|256",
      "nagerecht|105",
      "nagerecht/desserts|134",
      "nagerecht/gebak|104",
      "nagerecht/kazen|3",
      "ontbijt|20",
      "tussendoortje|25",
      "tussengerecht|36",
      "voorgerecht|305"
    ]
  }
}

Every facet consists of the facet name and the facet count separated by a pipe character. In the search response above for the given search query, there are 290 results that have the course "bijgerecht", 64 results have the course "brunch", 1041 results have the course "hoofdgerecht", etc.

5.4.2. Range Facets

Range facets produce multiple range buckets over numeric fields or date fields.

The search response below show the fat_int range facets:

{
  "header": ...,
  "results": ...,
  "facet_ranges": {
    "fat_int": {
      "start": 0,
      "end": 160,
      "gap": 20,
      "facets": [
        "0|838",
        "20|840",
        "40|249",
        "60|42",
        "80|9",
        "100|1",
        "140|1",
        "160|2"
      ]
    }
  }
}

Here, the facet buckets start at 0 (grams of fat), end at 160 (grams of fat) with gaps of 20 (grams of fat). So there are 838 results with fat between 0 and 20 (grams), 840 results with fat between 20 and 40 (grams) and so on. The last bucket of 160 (grams) contains all the results with fat greater than or equal to 160 (grams).

5.5. Retrieving Filters Values

To get the list of available ids or facet names for each filter, there are two methods:

5.5.1. Using the Search Filters API Call

To retrieve the ids and values for each filter, use the following API call:

GET /v1/recipes/search/filters

This call returns all the recipe related entities with ids. These ids can then be used in the search API call using the _id / _multi_id type filters.

5.5.2. Using the Search API Call

To retrieve all possible facets, use the search API call to return facets and set the items_per_page to 0:

{
    "return_facets": "true",
    "items_per_page": 0
}

This call returns all facet names that can be used in the search API call using the _str / _multi_str type filters.

5.6. Autocomplete Recipe Titles

To autocomplete recipe titles, use the following API call:

GET /v1/recipes/suggest/title

To find all recipes that have the string cake in the title, use the following request:

GET /v1/recipes/suggest/title?query=cake

This call returns the id, title and url of every active recipe that has the string cake anywhere in the title as a word, or as part of a word.

By default, this call returns a maximum of 10 recipes. The optional max parameter can be used to change this. For example, the following API call:

GET /v1/recipes/suggest/title?query=cake&max=20

returns a maximum of 20 recipes.

5.7. Registering Views and Ratings

Views and ratings can be used to track popularity of recipes in terms of how many views a recipe has had and the average rating of a recipe.

To register a view for a recipe, use the following API call:

POST /v1/recipes/{id}/view

For example, the API call POST /v1/recipes/12/views will add a view to the view count of recipe 12.

To let users give a rating between 1 and 10 to a recipe, use the following API call:

POST /v1/recipes/{id}/rate

For example, the API call POST /v1/recipes/12/rate with the request:

{
    "rating": 7,
}

assigns a rating of 7 to the recipe with id 12.

6. Menus

Menus are collections of recipes. To retrieve all defined menus, use the following API call:

GET /v1/menus

This call supports the optional parameters filter_year and filter_month to retrieve all menus from a certain year and/or month. For example, the API call:

GET /v1/menus?filter_year=2015&filter_month=12

retrieves all menus from december 2015.

To retrieve a single menu including the recipes, use the following API call:

GET /v1/menus/{id}

For example, the API call GET /v1/menus/15 retrieves menu with id 15.

7. Appendix

7.1. Image Variants

7.1.1. 1:1 Aspect Ratio

Name Quality Resolution

low-780x780-ratio-1x1

low

780x780

med-1920x1920-ratio-1x1

medium

1920x1920

high-3840x3840-ratio-1x1

high

3840x3840

7.1.2. 2:1 Aspect Ratio

Name Quality Resolution

low-780x390-ratio-2x1

low

780x390

med-1920x960-ratio-2x1

medium

1920x960

high-3840x1920-ratio-2x1

high

3840x1920

7.1.3. 4:3 Aspect Ratio

Name Quality Resolution

low-780x585-ratio-4x3

low

780x585

med-1920x1440-ratio-4x3

medium

1920x1440

high-3840x2880-ratio-4x3

high

3840x2880

7.1.4. 3:4 Aspect Ratio

Name Quality Resolution

low-585x780-ratio-3x4

low

585x780

med-1440x1920-ratio-3x4

medium

1440x1920

high-2880x3840-ratio-3x4

high

2880x3840

7.2. Recipe Search Filter Parameters

Parameter Description

full_text

Filter for title, subtitle, ingredients and preparations text fields.

ingredient_text

Filter for ingredient text fields.

created_date

Filter for recipe create date.

updated_date

Filter for recipe last update date.

preparation_time_int

Filter recipe preparation time.

kcal_int

Filter for recipe amount of kilokalories.

fat_int

Filter for recipe amount of fats.

saturated_fat_int

Filter for recipe amount of saturated fats.

carbs_int

Filter for recipe amount of carbohydrates.

protein_int

Filter for recipe amount of proteins.

fibers_int

Filter for recipe amount of fibers.

salt_int

Filter for recipe amount of salt.

persons_int

Filter for recipe serving size.

rating_average_int

Filter for recipe average rating.

view_count_int

Filter for recipe total view count.

status_id

Filter for recipe status id.

status_str

Filter for recipe status facet name.

difficulty_id

Filter for recipe difficulty id.

difficulty_str

Filter for recipe difficulty facet names.

course_multi_id

Filter for recipe course id(s).

course_multi_str

Filter for recipe course facet name(s).

kitchen_multi_id

Filter for recipe cuisine id(s).

kitchen_multi_str

Filter for recipe cuisine facet name(s).

magazine_multi_id

Filter for recipe magazine issue id(s).

magazine_multi_str

Filter for recipe magazine issue facet name(s).

tag_multi_id

Filter for recipe tag id(s).

tag_multi_str

Filter for recipe tag facet name(s).

ingredient_multi_id

Filter for recipe ingredient id(s).

ingredient_multi_str

Filter for recipe ingredient facet name(s).

wine_multi_id

Filter for recipe wine advice id(s).

wine_multi_str

Filter for recipe wine advice facet name(s).