Recipe Management API and Private Search API Documentation

The Recipe Management API and Private Search API provides the ability to manage and search your private recipes.

Overview

The Recipe Book functionality provides the ability to manage and search your private recipes. It consists of two parts:

  • Recipe Book Management API – store, analyze, publish & delete your recipes.
  • Recipe Search API – search your recipes.

The APIs are accessible through two separate but linked accounts. This allows for better protection of the recipes, as the Search API can only see the published recipes and cannot modify anything.

The Recipe Book Management API is organized around the idea of having a draft and published variants of the recipe. This is done to ensure that the API user can see and verify the analyzed recipe before it gets published.

The above OpenAPI specification can be found here.

More information on OpenAPI can be found at: https://swagger.io/.

Additionally, the Recipe Search API documentation can be found here.

Authentication

The API uses HTTP Basic authentication with the app-id for username and app-key for password.

Optimistic Locking

To prevent potential problems from simultaneous changes to the same recipe, this API uses optimistic locking. This is done through the Edamam-Record-Version HTTP headers. Many of the requests return this header to indicate the current version, and some support or require the header in the request.

Note that the versions are used only for synchronization purposes. The API does not remember the data from past versions, and one cannot rely on it to revert to an older state.

See the OpenAPI specification for more details.

Record State

Here is a state diagram from the management API’s perspective:

State Diagram

A recipe book record can be in one of the following states:

  • draft – Only a draft version exists.
  • published – Only a published version exists.
  • modified – Both published and draft versions exist.
  • deleted – The record has been deleted.

If both the draft and published variants of a recipe are deleted, the record goes in the deleted state, and is still present. Hence, a deleted recipe is different from a recipe that never existed. In order to recreate a deleted recipe, you’ll need to use the correct Edamam-Record-Version header for the request to succeed.

The current state of the record is returned in the Edamam-Record-State HTTP header.

See the OpenAPI documentation above for more details.

Recipes in other Languages

The Recipe Book and Recipe Search APIs now support adding recipe translations in other languages. Please note, that the recipe analyzer still supports only English, so the Recipe Book API needs an English variant of the recipe in all cases.

We can now add, update or remove translations by using “Update recipe draft” and “Remove recipe draft” end-points. Both of them now accept the `Content-Language` header. If the header is missing, it’s treated as English (`en`) for backwards compatibility.

The “Get draft”, “Get published”, “Get draft search view” and “Get published search view” requests of the Recipe Book API are also updated to support multiple languages. There, you need to use the `Accept-Language` header to request the recipe/search-view in the specified language.

The Recipe Search API is also updated in similar manner. Use the `Accept-Language` request header to specify the language.

Generally, `Content-Language` specifies the language of the content that you’re sending, while `Accept-Language` specifies the language that you want to see in the response.

See the use-cases below for examples. See the updated OpenAPI documentation for more details.

Use Cases

Create a New Draft Recipe

There are two ways to create a new recipe, one is if the user has an existing recipe ID that they want to use, and the other is when they want an ID to be automatically generated by Edamam.

With Existing ID

PUT https://api.edamam.com/api/recipe-book/v1/{app-id}/draft/{recipe-id}
Content-Type: application/json; charset=UTF-8
  
{
  "title": "string",
  "ingr": [
    "string"
  ],
  "summary": "string",
  "yield": "string",
  "totalTime": "string",
  "prep": [
    "string"
  ],
  "img": "string",
  "tags": [
    "string"
  ]
}

Without Existing ID

POST https://api.edamam.com/api/recipe-book/v1/{app-id}/draft
Content-Type: application/json; charset=UTF-8
  
{
  "title": "string",
  "ingr": [
    "string"
  ],
  "summary": "string",
  "yield": "string",
  "totalTime": "string",
  "prep": [
    "string"
  ],
  "img": "string",
  "tags": [
    "string"
  ]
}

Note, that the two API calls will behave differently if you repeat them:

  • The access point with existing ID will fail on the second call.
  • The access point with generating ID will generate two recipes with different IDs.

In both cases (and when updating a recipe), you can use a special syntax for the ingredient lines, to specify exact foods to be used:

{
  "ingr": [
    "1 tablespoon of {our special ingredient|00123}"
  ]
}

With this, the analyzer will see the string "our special ingredient|00123", while the search API will show "1 tablespoon of our special ingredient".

The response also contains `Edamam-Ingredients-Statuses` header, which has information about each line of the `ingr` request. It looks like this:

      
  edamam-ingredients-statuses: [OK],[OK],[MISSING_QUANTITY],[UNRECOGNIZED_FOOD],[OK],[OK,OK],[OK],[UNPROCESSED_LINE]

This tells us there are 8 lines:

  • 1. The first 2 lines were processed without errors. Each of them contains a single ingredient.
  • 2. The third line was processed, no quantity information could be extracted.
  • 3. We couldn’t recognize the food from the fourth line.
  • 4. The sixth line has 2 ingredients, both of which were recognized without problems.
  • 5. We were unable to process the eighth line.

The currently returned status codes are:

  • `OK` – No problems.
  • `MISSING_QUANTITY` – Missing quantity.
  • `UNRECOGNIZED_FOOD` – Unrecognized food.
  • `UNPROCESSED_LINE` – The line could not be processed.

Please note that a recipe could still be considered as correctly extracted even if there are some lines for which we report problems.

Read the Draft Recipe and the Analyzed View

To obtain the unanalyzed draft recipe, you can use the following request:

GET https://api.edamam.com/api/recipe-book/v1/{app-id}/draft/{recipe-id}

And to get the analyzed recipe, in the same way that it would show up in the Recipe Search API, you can use:

GET https://api.edamam.com/api/recipe-book/v1/{app-id}/draft/{recipe-id}/search-view

Publish a Recipe

Publishing a draft recipe is done with the following request:

POST https://api.edamam.com/api/recipe-book/v1/{app-id}/draft/{recipe-id}/publish
Edamam-Record-Version: {version}

If this recipe was previously published, this request will replace that with the current draft version.

Please note, that this call only initiates the publishing process. It takes some time before the new recipe actually appear in the results of the Recipe Search API.

Modify a Recipe

To modify a recipe, use the following request:

PUT https://api.edamam.com/api/recipe-book/v1/{app-id}/draft/{recipe-id}
Content-Type: application/json; charset=UTF-8
Edamam-Record-Version: {version}
  
{
  "title": "string",
  "ingr": [
    "string"
  ],
  "summary": "string",
  "yield": "string",
  "totalTime": "string",
  "prep": [
    "string"
  ],
  "img": "string",
  "tags": [
    "string"
  ]
}

(The difference between this and the request for creating a new recipe is that this one sends the Edamam-Record-Version HTTP header.)

Add a Translation

To add a translation to an existing recipe, use the following request:

PUT https://api.edamam.com/api/recipe-book/v1//draft/
Content-Type: application/json; charset=UTF-8
Content-Language: 
Edamam-Record-Version: 
                                
{
  "title": "string",
  "ingr": [
    "string"
  ],
  "summary": "string",
  "yield": "string",
  "totalTime": "string",
  "prep": [
    "string"
  ],
  "img": "string",
  "tags": [
    "string"
  ]
}

Discard Draft

To discard the current draft version, use the following:

DELETE https://api.edamam.com/api/recipe-book/v1/{app-id}/draft/{recipe-id}
Edamam-Record-Version: {version}

This will not affect the published version (if any).

Remove a translation

To remove the draft or published translation, use:

DELETE https://api.edamam.com/api/recipe-book/v1//draft/
Content-Language: 
Edamam-Record-Version:

or:

DELETE https://api.edamam.com/api/recipe-book/v1//published/
Content-Language: 
Edamam-Record-Version:

Read the Published Recipe and the Analyzed View

To obtain the unanalyzed published recipe, use the following request:

GET https://api.edamam.com/api/recipe-book/v1/{app-id}/published/{recipe-id}

And to get the analyzed recipe, in the same way that it would show up in the Recipe Search API, you can use:

GET https://api.edamam.com/api/recipe-book/v1/{app-id}/published/{recipe-id}/search-view

Unpublish

To remove the published version, use:

DELETE https://api.edamam.com/api/recipe-book/v1/{app-id}/published/{recipe-id}
Edamam-Record-Version: {version}

If there is a draft version, the record will switch to draft state, otherwise it will go to deleted state.

Recipe Search API

The Recipe Search API is accessible through the https://api.edamam.com/api/recipes/v2 end point. It supports all the configured features of the normal search plus:

  • The ability to specify whether we are searching:
    • the public recipes (type=public)
    • this account’s private recipes (type=user)
    • both (type=any)
  • The ability to filter by tags through the use of the tag parameter.

See the Recipe Search API Documentation for more details.

Please note, that normally it takes about 20-25 minutes for a published recipe to appear in the search API, but in extreme cases it can take several hours.

Also, please consider using the field parameter to specify which fields to be included in the response. This can greatly reduce the response size and thus make the API run faster and require less networking traffic and memory for the client to handle it.

Example Requests

Search for “chicken” in the Recipe Book Recipes

GET https://api.edamam.com/api/recipes/v2?app_id={app-id}&app_key={app-key}type=user&q=chicken&field=uri&field=label

Show all the Private Recipes Tagged with “party” or with tag “family”

GET https://api.edamam.com/api/recipes/v2?app_id={app-id}&app_key={app-key}type=user&tag=party&tag=family&field=uri&field=label&field=tags

Searching in Spanish

GET https://api.edamam.com/api/recipes/v2?app_id=&app_key=type=user&q=pollo&field=uri&field=label
Accept-Language: es