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
.
- 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
, thelogo
, 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 thematches
array (i.e., matching recipes) in the Search Recipes API responses contain asourceDisplayName
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
- 409 – API 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¶m[]=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
- All parameters are optional and can be used in any combination.
- 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.
- If you specify a multi-word phrase to the q parameter, every word has to match something in each matching recipe:
- A word in the title
- An ingredient
- An assigned cuisine, course, or holiday
- A diet or allergy for which the recipe would be acceptable
- 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
- If you specify multiple excludedIngredients, a recipe may not contain any of them.
- Yummly has a hierarchy of ingredients. If you exclude fruit, you will not get any recipe with apples, oranges, etc.
- 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.
- If this description is unclear, just play with the Yummly search page. These rules are meant to match the intuitive expectations of a user.
- 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.
- The API may return a redirect HTTP status code (302) which you should follow.
- 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.
- 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"}, …]);
- 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.
- 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
- 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
- To search for “Onion Soup” recipes append
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
- To search for “Onion Soup” recipes which have pictures, append
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
- To search for “Onion Soup” recipes which include garlic and cognac append
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
- To search for “Onion Soup” recipes which do not include “onion soup mix” append
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
- To search for “Onion Soup” recipes that are Dairy-Free and Gluten-Free append
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
- To search for “Onion Soup” recipes that are Pescetarian and Lacto vegetarian append
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
- To search for “Onion Soup” recipes that match American Cuisine append
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
- To exclude American recipes from a search for “Onion Soup” append
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
- To search for “Onion Soup” recipes that are Appetizers append
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
- To exclude Appetizer recipes from a search for “Onion Soup” append
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
- To search for “Onion Soup” recipes for Thanksgiving append
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
- 4th of July, Chinese New Year, Christmas, Easter, Fall, Game Day, Halloween, Hanukkah, New Year, Passover, Spring, St. Patrick's Day, Summer, Thanksgiving, Valentine's Day, Winter
- To exclude Thanksgiving recipes from a search for “Onion Soup” append
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
- To search for “Onion Soup” recipes that take less than 5400 seconds (in other words, less than 90 minutes), append
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
- 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
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
- For example, if you want 10 recipes per page and want to see the second page of results, you would append
flavor.{sweet|meaty|sour|bitter|salty|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
- To add facet counts for matching diets, append
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?_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, appendFrench-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 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.