Yummly API Documentation

About the Yummly API

  • Protocol: The transport is HTTP. The Yummly API tries to conform to REST principles.
  • API Endpoint: The endpoint for the current API version is http://api.yummly.com/v1. All URLs mentioned below are relative to the endpoint. The endpoint address may change in future versions of the API.
  • HTTPS: You can also hit the end point using https at https://api.yummly.com/v1
  • API Calls: There are currently two API calls: Get Recipe and Search Recipes.
  • Response Format: The data returned by the API is encoded as JSON (Content-Type: application/json). The character encoding is UTF-8. Future versions of the API may introduce other formats which will be selectable through the use of Accept and Accept-Charset headers. In the current version these headers are ignored.
  • JSONP: The API calls listed below also support JSONP (Content-Type: text/javascript) as an alternative encoding. If you pass a URL parameter named callback to the end point, the returned value will be wrapped in a function call where the function name is the value of the callback parameter. For example &callback=YourFunctionNameHere
  • Compression: The API supports compressing response data. This can be selected through the use of the Accept-Encoding header. If your client is not in the US-East region of Amazon EC2, you will benefit from using Accept-Encoding:gzip.
  • Caching: The API supports caching through the use of the ETag and Last-Modified response headers and the corresponding If-None-Match and If-Modified-Since request headers. Clients are encouraged to use these to improve performance. The API will return status code 304 if the cached data is still valid.
  • Redirect Handling: API calls may return temporary redirects (302) which the clients should follow. In general, the clients should expect to receive any of the standard HTTP status code and handle them according to the HTTP spec

Developer Requirements

1- Authentication

In order to call the API, you need to register as a developer at our developer site and accept the terms of use. You will then be issued an application ID and a key. You must either pass these with each API call in HTTP headers:

X-Yummly-App-ID:app-id
X-Yummly-App-Key:app-key

or include them as URL parameters:

_app_id=app-id&_app_key=app-key

If your id and key are invalid, or if you exceed your API rate limit, the server will respond with the HTTP status code 409.

2- Attribution Requirements

Whenever you display information obtained from the Yummly API to your users, you must give attribution to Yummly and the source of the recipe. The objects returned by the Get Recipe and Search Recipes API calls contain an attribution subobject which consists of the following fields:

  • html: If your application uses HTML to display data to the users, you must include the contents of the html field verbatim in a visible place near the data. You can ignore the other fields. You may not modify the HTML snippet.
  • url, text, logo: If your application is native (desktop or mobile) or otherwise doesn’t use HTML, you must display the text, the logo, and a link to the URL in a visible place near the data. Clicking this should open a browser on the url. You may not modify the URL, the link text, or the logo image.
  • source: The recipe objects returned by the Get Recipe and Search Recipes API calls contain source attribution subobject which consists of the following fields – sourceRecipeUrl, sourceSiteUrl, sourceDisplayName. You must display the sourceDisplayName, and a link to either the sourceRecipeUrl and/or sourceSiteUrl in a visible place near the data. Clicking this should open a browser on the url. You may not modify the sourceRecipeUrl, sourceSiteUrl, or the sourceDisplayName.

3- Plans and Rate Limits

You must choose a rate limit plan when you sign up for the API. If you’d like a higher rate limit than is offered by any of the plans, please contact us at api@yummly.com.

Error Codes

  • 400 – Bad Request
  • 409API Rate Limit Exceeded
  • 500 – Internal Server Error

Using the Search Recipes API Call

This call is similar in functionality to the Yummly recipe search.

Performing GET requests to search for recipes

  • The base url for the Search Recipes GET is http://api.yummly.com/v1/api/recipes?_app_id=app-id&_app_key=app-key&your _search_parameters
  • Some of the parameters support passing multiple values; in these cases, we follow the AJAX convention: param[]=value1&param[]=value2&…
  • Don’t forget to URL-encode parameter names and values (i.e., [ and ] become %5B and %5D).
  • This sample illustrates the structure of Search Recipes response.

Search API Semantics

  1. All parameters are optional and can be used in any combination.
  2. The criteria you pass via the various parameters are combined with the AND operator (set conjunction). In other words, every recipe has to match the search phrase and satisfy the ingredient, cuisine, course, holiday, time, nutrition, price, and taste restrictions as described below.
  3. If you specify a multi-word phrase to the q parameter, every word has to match something in each matching recipe:
    1. A word in the title
    2. An ingredient
    3. An assigned cuisine, course, or holiday
    4. A diet or allergy for which the recipe would be acceptable
  4. If you specify multiple allowed ingredients or allergies or diets, AND is implied: a recipe has to include all ingredients and to be compatible with all allergies and diets
  5. If you specify multiple excludedIngredients, a recipe may not contain any of them.
  6. Yummly has a hierarchy of ingredients. If you exclude fruit, you will not get any recipe with apples, oranges, etc.
  7. If you specify multiple allowed diets, cuisines, holidays, or courses, OR is implied: a recipe must match at least one of the diets, one of the cuisines, etc.
  8. If this description is unclear, just play with the Yummly search page. These rules are meant to match the intuitive expectations of a user.
  9. WARNING It is possible to filter a search to the point that the API returns 0 results that match your filter+query set.

Search Metadata

We keep dictionaries of the possible values of our search parameters which are defined in the section “Parameters”. Each parameter documented in the “Parameters” section contains a link to the corresponding metadata dictionary.

  1. The API may return a redirect HTTP status code (302) which you should follow.
  2. The final target of the redirect will return HTTP caching headers, which you should respect. This data changes infrequently and your application will benefit by caching it. More specifically, you should use the If-Modified-Since and If-None-Match headers in your request.
  3. The objects returned by these APIs are not plain JSON but JSONP. The structure is something like: bq. set_metadata('course', [{"id":"course-Appetizers","description":"Appetizers","searchValue":"course^course-Appetizers"}, …]);
  4. If your app is in the browser, use your method of choice to process this JSONP response. If your app is not in the browser you can parse the response by simply skipping the set_matadata(‘name’, part and the trailing ); and treating the rest of the content as a JSON array.
  5. The elements of the array are objects with several fields. Two fields are important. The description field contains the human-readable value you can show to an (English-speaking) user. The searchValue field contains the string that has to be passed exactly to the corresponding parameter of the search API call. I.e., for the example above, to include appetizers in your search, use &allowedCourse[]=course^course-Appetizers
  6. Again, don’t forget to URL-encode!

Parameters

  • q: This is the search phrase. Use space to separate words (url-encoded as either + or %20).
    • To search for “Onion Soup” recipes append &q=onion+soup or &q=onion%20soup
  • requirePictures: Setting this to “true” means to only return recipes with photos.
    • To search for “Onion Soup” recipes which have pictures, append &requirePictures=true
  • allowedIngredient[] : Specifying ingredients against this parameter means that all search results must include recipes with the specified ingredient(s) and will exclude any recipes that do not list the specified ingredient(s). Set the parameter equal to the searchValue of an ingredient. This parameter can be repeated more than once.
    • Ingredient metadata searchValues: http://api.yummly.com/v1/api/metadata/ingredient?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • To search for “Onion Soup” recipes which include garlic and cognac append both &allowedIngredient[]=garlic and &allowedIngredient[]=cognac
  • excludedIngredient[] : Specifying ingredients against this parameter means that search results will exclude recipes with the specified ingredient(s). Set the parameter equal to the searchValue of an ingredient. This parameter can be repeated more than once.
    • Ingredient metadata searchValues: http://api.yummly.com/v1/api/metadata/ingredient?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • To search for “Onion Soup” recipes which do not include “onion soup mix” append &excludedIngredient[]=onion%20soup%20mix and &excludedIngredient[]=gruyere
  • allowedDiet[], allowedAllergy[] : Specifying diets or allergy parameters mean that all search results must exclude recipes that do not match those specified diets or allergies. Set the parameter equal to the searchValue of a diet or allergy. This parameter can be repeated more than once.
    • metadata searchValues
      • Diet searchValues – http://api.yummly.com/v1/api/metadata/diet?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
      • Allergy searchValues – http://api.yummly.com/v1/api/metadata/allergy?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Examples
      • Diet – To search for “Onion Soup” recipes that are Pescetarian and Lacto vegetarian append &allowedDiet[]=390^Pescetarian and &allowedDiet[]=388^Lacto vegetarian
      • Allergy – To search for “Onion Soup” recipes that are Dairy-Free and Gluten-Free append &allowedAllergy[]=396^Dairy-Free and &allowedAllergy[]=393^Gluten-Free
  • allowedCuisine[], allowedCourse[], allowedHoliday[]: Specifying a searchValue against an allowedCuisine, allowedCourse, or allowedHoliday will return search results with recipes that match that searchValue. This parameter can be repeated more than once.
    • metadata searchValues
      • Cuisine searchValues – http://api.yummly.com/v1/api/metadata/cuisine?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
      • Course searchValues – http://api.yummly.com/v1/api/metadata/course?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
      • Holiday searchValues – http://api.yummly.com/v1/api/metadata/holiday?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Examples
      • Cuisine – To search for “Onion Soup” recipes which match American Cuisine append &allowedCuisine[]=cuisine^cuisine-american
      • Course – To search for “Onion Soup” recipes which are Appetizers append &allowedCourse[]=course^course-Appetizers
      • Holidays – To search for “Onion Soup” recipes which are good for Christmas append &allowedCourse[]=holiday^holiday-christmas
  • excludedCuisine[], excludedCourse[], excludedHoliday[]: Specifying a searchValue against an excludedCuisine, excludedCourse, or excludedHoliday will return search results that exclude recipes with that searchValue. This parameter can be repeated more than once.
    • metadata searchValues
      • Cuisine searchValues: http://api.yummly.com/v1/api/metadata/cuisine?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
      • Course searchValues: http://api.yummly.com/v1/api/metadata/course?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
      • Holiday searchValues: http://api.yummly.com/v1/api/metadata/holiday?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Examples
      • Cuisine – To exclude American recipes from a search for “Onion Soup” append &excludedCuisine[]=cuisine^cuisine-american
      • Course – To exclude Appetizers from a search for “Onion Soup” append &excludedCourse[]=course^course-Appetizers
      • Holiday – To exclude Christmas recipes from a search for “Onion Soup” append &excludedCourse[]=holiday^holiday-christmas
  • maxTotalTimeInSeconds : Search for recipes that do not exceed a specified max total cook + prep time in seconds.
    • To search for “Onion Soup” recipes that take less than 5400 seconds (in other words, less than 90 minutes), append &maxTotalTimeInSeconds=5400
  • nutrition.ATTR_NAME.{min|max} : Set the range of allowed values for a given nutrition attribute (see below for the list of supported nutrition attributes) by setting a min and/or a max. If min or max are omitted, 0 and infinity are assumed. The values of the parameter change depending on the nutrition attribute being used.
    • For example if you are looking for recipes with a lot of Potassium, try setting a min of 3000 mg and a max of the Daily Suggested Value of 3500 mg, append &nutrition.K.min=3 and &nutrition.K.max=3.5 . Remember to convert to grams from milligrams!
    • Likewise, if you creating a filter recipes with no carbs that are high in protein, try appending &nutrition.CHOCDF.min=0 and &nutrition.CHOCDF.max=0 and &nutrition.PROCNT.min=20 and &nutrition.PROCNT.max=50

Supported Nutrition Attributes (ATTR_NAME):

Nutrition value to pass to the API Description Implied Units
K Potassium, K gram
NA Sodium, Na gram
CHOLE Cholesterol gram
FATRN Fatty acids, total trans gram
FASAT Fatty acids, total saturated gram
CHOCDF Carbohydrate, by difference gram
FIBTG Fiber, total dietary gram
PROCNT Protein gram
VITC Vitamin C, total ascorbic acid gram
CA Calcium, Ca gram
FE Iron, Fe gram
SUGAR Sugars, total gram
ENERC_KCAL Energy kcal
FAT Total lipid (fat) gram
VITA_IU Vitamin A, IU IU
  • maxResult, start : The maxResult and start parameters allow pagination and # of results control. By default 6 recipes are returned by the search API.
    • For example, if you want 10 recipes per page and want to see the second page of results, you would append &maxResult=10&start=10. Start is set to 10 versus because the numbering for results starts at 0 (versus 1).
  • flavor.{sweet|meaty|sour|bitter|sweet|piquant}.{min|max} Set the ranges for taste attributes (this corresponds to the taste sliders on the Yummly.com search page). The values of min and max are between 0 and 1.
    • The “Meaty” attribute is equivalent to “Savory” in the Yummly search.
    • The “Piquant” attribute is equivalent to “Spicy” in the Yummly search.
    • To search for recipes which are very sweet but are not very spicy, you might append &flavor.sweet.min=0.8 and &flavor.sweet.max=1 and &flavor.piquant.min=0 and &flavor.piquant.max=0.2
  • facetField[] : The Search Recipes API supports facet counts for ingredient and diet. When this parameter is called, the response will include a facetCounts object that lists the matching diets or ingredients and how many results match each diet or ingredient.
    • To add facet counts for matching diets, append &facetField[]=diet
    • To add facet counts for matching ingredients, append &facetField[]=ingredient

Consumer Guide for Search Recipes Response

The following documentation is for objects returned from the Search Recipes API Call.
The search API response objects consist of:

attribution : see Attribution Requirements Always present in response.

totalMatchCount : The total number of recipes that matched the query (not just the current page of results).

facetCounts : The matching facets for the entire query result set (not just the current page) for each of the fields listed in the facetField[] parameter. Lists each matching and the number of times that value occurs in a recipe in the query result set. The values that don’t occur (i.e., zero counts) are omitted.

matches : An array of the matching recipes. This is a window into the entire result set controlled by the maxResult and start parameters. Note that the data structure describing each recipe is different that the data structure returned by the Get Recipe API. Each object in matches has the following data:

  • attributes :
    • course : An array of the cources associated with this recipe.
    • cuisine : An array of the cuisines associated with this recipe.
    • holiday : An array of the holidays associated with this recipe.
  • flavors : The flavor scores for this recipe.
    • salty : Saltiness on a range of 0 to 1.
    • sour : Sourness on a range of 0 to 1.
    • sweet : Sweetness on a range of 0 to 1.
    • bitter : Bitterness on a range of 0 to 1.
    • meaty : Savoryness on a range of 0 to 1.
    • piquant : Spiciness on a range of 0 to 1.
  • rating : The Yummly rating score for a recipe.
  • id : The reference id for this recipe that can be used to GET the full recipe details from the Get Recipe API Call. Always present in response.
  • smallImageUrls : An array of small thumbnail images for this recipe.
  • sourceDisplayName : The source site of this recipe.
  • totalTimeInSeconds : The prep time plus cook time for this recipe in seconds.
  • ingredients : An array of the ingredients in this recipe. Always present in response.
  • recipeName : The display name for this recipe. Always present in response.

criteria : This states the query parameters for the result set.

Using the Get Recipe API Call

This call is equivalent in functionality to a Yummly recipe page.

Performing GET requests for Recipe IDs

  • The base url for the a Get Recipe GET is http://api.yummly.com/v1/api/recipe/recipe-id where recipe IDs may be obtained from the Search Recipes call. The recipe ID is the part of a Yummly recipe page URL after the last slash: http://www.yummly.com/recipe/RECIPE-ID
    For example, to request the response for French Onion Soup by Ree Drummond The Pioneer Woman, append French-Onion-Soup-The-Pioneer-Woman-Cooks-_-Ree-Drummond-41364
  • This sample illustrates the structure of Get Recipe response.

Consumer Guide for Get Recipe Response

The following documentation is for objects returned from the Get Recipe API Call.
The Get Recipe response objects consist of:

attribution : see Attribution Requirements Always present in response.

ingredientLines : The ingredient lines for the recipe, in the order they should be displayed. Always present in response.

flavors : The flavor scores for this recipe.

  • Piquant : Spiciness on a range of 0 to 1.
  • Bitter : Bitterness on a range of 0 to 1.
  • Sweet : Sweetness on a range of 0 to 1.
  • Meaty : Savoryness on a range of 0 to 1.
  • Salty : Saltiness on a range of 0 to 1.
  • Sour : Sourness on a range of 0 to 1.

nutritionEstimates : The nutritional composition of the recipe, in the form of a list of nutrients and their amounts, per serving. We will return nutrition estimates only for those recipes where we are reasonably confident in their accuracy. These are only estimates and you should be clear about that in what you tell your users.

  • attribute : Nutrition attribute’s search parameter name.
  • description : Display name of this nutrition attribute.
  • value : Nutrition attribute value for this recipe.
  • unit : Implied unit of measure.
    • name : Single unit display name for unit of measure.
    • abbreviation : Single unit abbreviation for unit of measure.
    • plural : Plural display name for unit of measure.
    • pluralAbbreviation : Plural unit abbreviation for unit of measure.

images : An array of the images that should be displayed along with the recipe if images are available for this recipe. These can come in the following sizes when and where available.

  • hostedLargeUrl : large (360×240)
  • hostedMediumUrl : medium (180×120)
  • hostedSmallUrl : small (90×60)

name : The display name for this recipe. Always present in response.

yield : The number of servings this recipe produces.

totalTime : The prep time plus cook time for this recipe. If the time value is a number, it is in seconds. If it is a string, it is a human readable string. It is arbitrary as to whether it will be one or the other.

attributes :

  • holiday : An array of the holidays associated with this recipe.
  • course : An array of the cources associated with this recipe.
  • cuisine : An array of the cuisines associated with this recipe.

totalTimeInSeconds : The prep time plus cook time for this recipe in seconds.

rating : The Yummly rating for this recipe. This can return as null.

numberOfServings : The number of servings in a numeric format.

source : URLs and display name for the Source Recipe and Site.

  • sourceRecipeUrl : The original source url of this recipe.
  • sourceSiteUrl : The url of the source site of this recipe.
  • sourceDisplayName : The display name of the source site.

id : The recipe id of this recipe used against the Get Recipe API call. Always present in response.