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 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. The elements of the matches array (i.e., matching recipes) in the Search Recipes API responses contain a sourceDisplayName field, and you must display its value in a visible place near the data, without modifying it.

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, 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 Dictionaries

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
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
  • requirePictures: Setting this to “true” means to only return recipes with photos.
    • To search for “Onion Soup” recipes which have pictures, append &requirePictures=true
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &requirePictures=true
  • allowedIngredient[] : Specifying ingredients against the allowedIngredient[] parameter means that all search results must include recipes with the specified ingredient(s) and will exclude any recipes that do not contain the specified ingredient(s). This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one ingredient.
    • To search for “Onion Soup” recipes which include garlic and cognac append &allowedIngredient[]=garlic&allowedIngredient[]=cognac
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &allowedIngredient[]=garlic&allowedIngredient[]=cognac
    • The allowedIngredient[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an allowedIngredient[] searchValue is "garlic" to indicate you want to recipes which include garlic. To access the metadata dictionary for allowedIngredient[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/ingredient?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
  • excludedIngredient[] : Specifying ingredients against the excludedIngredient[] parameter means that search results will exclude recipes with the specified ingredient(s). This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one ingredient.
    • To search for “Onion Soup” recipes which do not include “onion soup mix” append &excludedIngredient[]=onion%20soup%20mix&excludedIngredient[]=gruyere
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &excludedIngredient[]=onion%20soup%20mix&excludedIngredient[]=gruyere
    • The excludeIngredient[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an excludedIngredient[] searchValue is "onion soup mix" to indicate you want to recipes which exclude onion soup mix. To access the metadata dictionary for excludedIngredient[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/ingredient?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
  • allowedAllergy[] : Specifying an allowedAllergy[] parameter means that search results will only include recipes whose ingredients are allowed for that allergy. This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one allergy.
    • To search for “Onion Soup” recipes that are Dairy-Free and Gluten-Free append &allowedAllergy[]=396^Dairy-Free&allowedAllergy[]=393^Gluten-Free
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &allowedAllergy[]=396^Dairy-Free&allowedAllergy[]=393^Gluten-Free
    • The allowedAllergy[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an allowedAllergy[] searchValue is "393^Gluten-Free" to indicate you want Gluten Free recipes. To access the metadata dictionary for allowedAllergy[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/allergy?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Supported Allergies
      • Dairy, Egg, Gluten, Peanut, Seafood, Sesame, Soy, Sulfite, Tree Nut, Wheat
  • allowedDiet[] : Specifying an allowedDiet[] parameter means that search results will only include recipes whose ingredients are allowed for that diet. This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one diet.
    • To search for “Onion Soup” recipes that are Pescetarian and Lacto vegetarian append &allowedDiet[]=390^Pescetarian&allowedDiet[]=388^Lacto vegetarian
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &allowedDiet[]=390^Pescetarian&allowedDiet[]=388^Lacto vegetarian
    • The allowedDiet[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an allowedDiet[] searchValue is "390^Vegan" to indicate you want Vegan recipes. To access the metadata dictionary for allowedDiet[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/diet?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Supported Diets
      • Lacto vegetarian, Ovo vegetarian, Pescetarian, Vegan, Vegetarian
  • allowedCuisine[] : Specifying an allowedCuisine[] parameter means that search results will only include recipes with that cuisine. This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one cuisine.
    • To search for “Onion Soup” recipes that match American Cuisine append &allowedCuisine[]=cuisine^cuisine-american
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &allowedCuisine[]=cuisine^cuisine-american
    • The allowedCuisine[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an allowedCuisine[] searchValue is "cuisine^cuisine-american" to indicate you want American cuisine recipes. To access the metadata dictionary for allowedCuisine[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/cuisine?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Supported Cuisines
      • American, Italian, Asian, Mexican, Southern & Soul Food, French, Southwestern, Barbecue, Indian, Chinese, Cajun & Creole, English, Mediterranean, Greek, Spanish, German, Thai, Moroccan, Irish, Japanese, Cuban, Hawaiin, Swedish, Hungarian, Portugese
  • excludedCuisine[] : Specifying an excludedCuisine[] parameter means that search results will exclude recipes with that cuisine. This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one cuisine.
    • To exclude American recipes from a search for “Onion Soup” append &excludedCuisine[]=cuisine^cuisine-american
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &excludedCuisine[]=cuisine^cuisine-american
    • The excludedCuisine[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an allowedCuisine[] searchValue is "cuisine^cuisine-american" to indicate you want American cuisine recipes. To access the metadata dictionary for excludedCuisine[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/cuisine?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Supported Cuisines
      • American, Italian, Asian, Mexican, Southern & Soul Food, French, Southwestern, Barbecue, Indian, Chinese, Cajun & Creole, English, Mediterranean, Greek, Spanish, German, Thai, Moroccan, Irish, Japanese, Cuban, Hawaiin, Swedish, Hungarian, Portugese
  • allowedCourse[] : Specifying an allowedCourse[] parameter means that search results will only include recipes with that course. This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one course.
    • To search for “Onion Soup” recipes that are Appetizers append &allowedCourse[]=course^course-Appetizers
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &allowedCourse[]=course^course-Appetizers
    • The allowedCourse[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an allowedCourse[] searchValue is "course^course-Appetizers" to indicate you want Appetizer recipes. To access the metadata dictionary for allowedCourse[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/course?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Supported Courses
      • Main Dishes, Desserts, Side Dishes, Lunch and Snacks, Appetizers, Salads, Breads, Breakfast and Brunch, Soups, Beverages, Condiments and Sauces, Cocktails
  • excludedCourse[] : Specifying an excludedCourse[] parameter means that search results will exclude recipes with that course. This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one course.
    • To exclude Appetizer recipes from a search for “Onion Soup” append &excludedCourse[]=course^course-Appetizers
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &excludedCourse[]=course^course-Appetizers
    • The excludedCourse[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an excludedCourse[] searchValue is "course^course-Appetizers" to indicate you want to exclude Appetizer recipes. To access the metadata dictionary for excludedCourse[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/course?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Supported Courses
      • Main Dishes, Desserts, Side Dishes, Lunch and Snacks, Appetizers, Salads, Breads, Breakfast and Brunch, Soups, Beverages, Condiments and Sauces, Cocktails
  • allowedHoliday[] : Specifying an allowedHoliday[] parameter means that search results will only include recipes with that holiday. This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one holiday.
    • To search for “Onion Soup” recipes for Thanksgiving append &allowedHoliday[]=holiday^holiday-thanksgiving
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &allowedHoliday[]=holiday^holiday-thanksgiving
    • The allowedHoliday[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an allowedHoliday[] searchValue is "holiday^holiday-thanksgiving" to indicate you want Thanksgiving recipes. To access the metadata dictionary for allowedHoliday[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/holiday?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Supported Holidays
      • Christmas, Summer, Thanksgiving, New Year, Super Bowl / Game Day, Halloween, Hanukkah, 4th of July
  • excludedHoliday[] : Specifying an excludedHoliday[] parameter means that search results will exclude recipes with that holiday. This parameter must be set equal to a searchValue in the Search Metadata Dicionary and can be repeated more than once to specify more than one holiday.
    • To exclude Thanksgiving recipes from a search for “Onion Soup” append &excludedHoliday[]=holiday^holiday-thanksgiving
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &excludedHoliday[]=holiday^holiday-thanksgiving
    • The excludedHoliday[] parameter must be set equal to a searchValue found in the Yummly Search Metadata Dictionaries. An example of an excludedHoliday[] searchValue is "holiday^holiday-thanksgivings" to indicate you want to exclude Thanksgiving recipes. To access the metadata dictionary for excludedHoliday[] searchValues, use the following end point: http://api.yummly.com/v1/api/metadata/holiday?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY
    • Supported Holidays
      • Christmas, Summer, Thanksgiving, New Year, Super Bowl / Game Day, Halloween, Hanukkah, 4th of July
  • 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
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &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&nutrition.K.max=3.5.
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &nutrition.K.min=3&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&nutrition.CHOCDF.max=0
      &nutrition.PROCNT.min=20&nutrition.PROCNT.max=50
      .
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &nutrition.CHOCDF.min=0&nutrition.CHOCDF.max=0
      &nutrition.PROCNT.min=20&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).
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &maxResult=10&start=10
  • 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&flavor.sweet.max=1&flavor.piquant.min=0
      &flavor.piquant.max=0.2

      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &flavor.sweet.min=0.8&flavor.sweet.max=1&flavor.piquant.min=0
      &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
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &facetField[]=diet
    • To add facet counts for matching ingredients, append &facetField[]=ingredient
      For example: http://api.yummly.com/v1/api/recipes?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY&q=onion+soup
      &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:

  • 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?_app_id=YOUR_ID&_app_key=YOUR_APP_KEY 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:

  • 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 with the recipe's preparation steps. - Please note that the Yummly API does not provide the prep steps. As part of attribution to the source, we require a link out to the source 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.