skip to navigation
skip to content

Not Logged In

yummly 0.4.0

Python package for Yummly API:

Python library for Yummly API:

Version: 0.4.0

NOTE: This library and its author are not affliated with Yummly.



$ python install

Using pip

$ pip install yummly

Current Dependencies

  • requests>=1.1.0


Use yummly.Client to create a client object to interact with the Yummly API.

The client accepts api_id, api_key, and timeout as init parameters:

from yummly import Client

# default option values

client = Client(api_id=YOUR_API_ID, api_key=YOUR_API_KEY, timeout=TIMEOUT, retries=RETRIES)

search ='green eggs and ham')
match = search.matches[0]

recipe = client.recipe(

Search Recipes

API endpoint:<params>

Search for recipes meeting certain criteria:

results ='bacon')

print 'Total Matches:', results.totalMatchCount
for match in results.matches:
    print 'Recipe ID:',
    print 'Recipe:', match.recipeName
    print 'Rating:', match.rating
    print 'Total Time (mins):', match.totalTimeInSeconds / 60.0
    print '----------------------------------------------------'

Limit your results to a maximum:

# return the first 10 results
results ='chicken marsala', maxResults=10)

Offset the results for pagination:

# return 2nd page of results
results ='pulled pork', maxResults=10, start=10)

Provide search parameters:

params = {
    'q': 'pork chops',
    'start': 0,
    'maxResult': 40,
    'requirePicutres': True,
    'allowedIngredient[]': ['salt', 'pepper'],
    'excludedIngredient[]': ['cumin', 'paprika'],
    'maxTotalTimeInSeconds': 3600,
    'facetField[]': ['ingredient', 'diet'],
    'flavor.meaty.min': 0.5,
    'flavor.meaty.max': 1,
    'flavor.sweet.min': 0,
    'flavor.sweet.max': 0.5,
    'nutrition.FAT.min': 0,
    'nutrition.FAT.max': 15

results =**params)

For a full list of supported search parameters, see section The Search Recipes Call located at:

Example search response:

Get Recipe

API endpoint:<recipe_id>

Fetch a recipe by its recipe ID:

recipe = yummly.recipe(recipe_id)

print 'Recipe ID:',
print 'Recipe:',
print 'Rating:', recipe.rating
print 'Total Time:', recipe.totalTime
print 'Yields:', recipe.yields
print 'Ingredients:'
for ingred in recipe.ingredientLines:
    print ingred

Example recipe response:

NOTE: Yummly's Get-Recipe response includes yield as a field name. However, yield is a keyword in Python so this has been renamed to yields.

Search metadata

API endpoint:<metadata_key>

Yummly provides a metadata endpoint that returns the possible values for allowed/excluded ingredient, diet, allergy, and other search parameters:


ingredients = client.metadata('ingredient')
diets = client.metadata('diet')
sources = client.metadata('source')

NOTE: Yummly's raw API returns this data as a JSONP response which parses off and then converts to a list containing instances of the corresponding metadata class.

API Model Classes

All underlying API model classes are in yummly/ The base class used for all models is a modified dict class with attribute-style access (i.e. both and obj['foo'] are valid accessor methods).

A derived dict class was chosen to accommodate painless conversion to JSON which is a fairly common requirement when using as an API proxy to feed your applications (e.g. a web app with running on your server instead of directly using the Yummly API on the frontend).


Tests are located in yummly/tests/. They can be executed using pytest from the root directory using makefile or pytest.

# using makefile
$ makefile test

# using pytest directly
$ py.test yummly

NOTE: Running the test suite will use real API calls which will count against your call limit. Currently, 22 API calls are made when running the tests.

Test Config File

A test config file is required to run the tests. Create tests/config.json with the following properties:

    "api_id": "YOUR_API_ID",
    "api_key": "YOUR_API_KEY"

This file will be loaded automatically when the tests are run.


This software is licensed under the BSD License.


  • Provide helpers for complex search parameters like nutrition, flavors, and metadata
File Type Py Version Uploaded on Size
yummly-0.4.0.tar.gz (md5) Source 2013-09-10 10KB
  • Downloads (All Versions):
  • 9 downloads in the last day
  • 77 downloads in the last week
  • 512 downloads in the last month