Punchfork Recipe API

Recipe Search

Endpoint:

http://api.punchfork.com/recipes?key={api-key}&{optional-params}

Parameters:

• q (optional) — Recipe search query. Same as what you'd type into the search box on punchfork.com (see search tips). May also be a URL to look up the recipe with that URL (either a publisher URL or a punchfork.com URL). If no query is provided, the first N top-rated recipes are returned.
• ingred (optional) (paid) — When set to either "true" or "1", recipe responses will include ingredients data.
• count (optional) — Max number of recipes to be returned. Defaults to 10, maximum is 50. If you want more than 50 recipes, use cursor pagination.
• cursor (optional) — Start the query at the specified cursor value. This is used for pagination.
• sort (optional) — Sort recipes by "r"ating (default), "d"ate published, or "t"rendingness.
• from (optional) — Only get recipes from a specific publisher. If set, this parameter should contain the full publisher name, e.g. "The Pioneer Woman" (see our full list of publishers). If this parameter is not provided, the API will return recipes from all publishers.
• likes (optional) — Only get recipes from a specific user's likes. If set, this parameter should contain the user's Punchfork username.
• startdate (optional) — Only get recipes published on or after this date. Must be a UTC datetime in ISO format.
• enddate (optional) — Only get recipes published on or before this date. Must be a UTC datetime in ISO format.
• total (optional) — When set to either "true" or "1", the response will include a "total" value which indicates the total number of recipes in the database matching the query. Must be used along with the q parameter.

Response:

The response is a JSON dictionary containing the following values:

• count — Number of recipes in the result. If the query yields no results, the count will be 0.
• next_cursor — Value that can be passed back to the endpoint as cursor to yield the next page of recipes for the same query. If the query yields no results, next_cursor will be an empty string.
• recipes — Array of recipes. The array is sorted in decreasing order by the key specified in the sort parameter (defaults to recipe rating). Each recipe is a dictionary containing the following values: title, source_url, pf_url, source_name, source_img, thumb, rating, twc, fbc, suc, published (UTC datetime in ISO format), shortcode, and optionally source_ingred, cat_ingred and canon_ingred. If the query yields no results, recipes will be an array of length 0.
• total (optional) — If the total parameter is set, this value indicates the total number of recipes in the database matching the query.

Example:

$ curl 'http://api.punchfork.com/recipes?key={key}&q=chicken+parmesan&count=2'
{
  "count": 2,
  "recipes": [
    {
      "rating": 99.562,
      "source_name": "Skinny Taste",
      "thumb": "http://img.punchfork.net/9414bb60098bd0b58115d2ad506a20bf_250x250.jpg",
      "title": "Healthy Baked Chicken Nuggets",
      "source_url": "http://www.skinnytaste.com/2011/04/healthy-baked-chicken-nuggets.html",
      "pf_url": "http://punchfork.com/recipe/Healthy-Baked-Chicken-Nuggets-Skinny-Taste",
      "published": "2011-04-12T13:00:00",
      "source_img": "http://2.bp.blogspot.com/-jJOVHp44U2E/TaRqUWBT_ZI/AAAAAAAAC-4/VQoL7rrCaKM/s1600/healthy-baked-chicken-nuggets.jpg",
      "shortcode": "upk7zQ",
      "twc": 120,
      "fbc": 3835,
      "suc": 614961
    },
    {
      "rating": 80.8558,
      "source_name": "The Pioneer Woman",
      "thumb": "http://img.punchfork.net/f2f020ef8f2dfc87d824547275ec7077_250x250.jpg",
      "title": "Chicken Cacciatore",
      "source_url": "http://thepioneerwoman.com/cooking/2010/10/chicken-cacciatore/",
      "pf_url": "http://punchfork.com/recipe/Chicken-Cacciatore-The-Pioneer-Woman",
      "published": "2010-07-21T14:00:00",
      "source_img": "http://static.thepioneerwoman.com/cooking/files/2010/10/5091364415_b1058dec47_o.jpg",
      "shortcode": "rro9yX",
      "twc": 80,
      "fbc": 2533,
      "suc": 1552
    }
  ],
  "next_cursor": "80.8557733148"
}

Real-time results:

Real-time data is a paid API feature.

The free API only returns recipes at least 1 month old.

The paid API make recipes available immediately after they enter our database, often just minutes after they're published on the web.

Ingredients data:

Ingredients data is a paid API feature.

• source_ingred lists the raw ingredient text from the source recipe.
• cat_ingred lists the categorized ingredients that Punchfork builds from source_ingred. This is a dictionary whose keys are category names (e.g. "Canned Goods") and whose values are the matching lists of ingredients. Each categorized ingredient has an easy to read format.
• canon_ingred lists the canonical ingredient terms that Punchfork builds from source_ingred. These are parsed ingredient names, singularized (e.g. "burgers" is changed to "burger"), canonicalized (e.g. "scallion" is changed to "green onion") and lowercased. Amounts ("2 tbsp") and modifiers ("diced") are discarded. Depending on what you want to do with the ingredients list, it can be easier to use canon_ingred rather than source_ingred.

Example with ingredients data:

$ curl 'http://api.punchfork.com/recipes?key={key}&q=salmon+with+couscous&count=1&ingred=true'
{
  "count": 1,
  "recipes": [
    {
      "rating": 53.8188,
      "source_name": "The Kitchn",
      "thumb": "http://img.punchfork.net/f9c6047f7958927a0cff232e0da16853_250x250.jpg",
      "title": "Quick Salmon & Couscous with Cilantro Vinaigrette",
      "source_url": "http://www.thekitchn.com/thekitchn/main-dish/recipe-sauteed-salmon-with-cilantro-vinaigrette-over-couscous-142129",
      "pf_url": "http://punchfork.com/recipe/Quick-Salmon-Couscous-with-Cilantro-Vinaigrette-The-Kitchn",
      "published": "2011-02-19T08:00:00",
      "source_img": "http://www.apartmenttherapy.com/uimages/kitchen/2011_03_22-Salmon.jpg",
      "shortcode": "mB2Pwv",
      "source_ingred": [
        "1 10-ounce box plain couscous (1 1/2 cups)",
        "1 10-ounce salmon fillet,skin removed and cut in 2 pieces",
        "1/2 teaspoon sumac",
        "Salt and pepper",
        "3 tablespoons olive oil",
        "1/4 cup cilantro,chopped",
        "2 scallions, thinly sliced",
        "2 tablespoons lemon juice"
      ],
      "cat_ingred": {
        "Cooking & Baking": [
          "Olive oil (3 tablespoons)",
          "Salt and pepper (1)",
          "Sumac (1/2 teaspoon)"
        ],
        "Drinks": [
          "Lemon juice (2 tablespoons)"
        ],
        "Pasta & Grains": [
          "1 10-ounce box plain couscous, plain (1 1/2 cups)"
        ],
        "Produce": [
          "Cilantro (1/4 cup)",
          "Scallions (2)"
        ],
        "Seafood": [
          "10-ounce salmon, fillet (1)"
        ]
      },
      "canon_ingred": [
        "coriander",
        "couscous",
        "green onion",
        "lemon juice",
        "olive oil",
        "salmon",
        "salt and pepper",
        "sumac"
      ]
    }
  ],
  "next_cursor": "53.8187618818"
}

Random Recipe

Endpoint:

http://api.punchfork.com/random_recipe?key={api-key}

Parameters:

• None

Response:

The response is a JSON dictionary containing the following values:

• recipe — A single recipe selected at random from the Punchfork database. The format is the same as in the /recipes endpoint.

Example:

$ curl 'http://api.punchfork.com/random_recipe?key={key}'
{
  "recipe": {
    "rating": 70.0612,
    "source_name": "Simply Recipes",
    "thumb": "http://img.punchfork.net/7cf6724743c607df27b9eebb9bf3134c_250x250.jpg",
    "title": "Beer Can Chicken",
    "source_url": "http://simplyrecipes.com/recipes/beer_can_chicken/",
    "pf_url": "http://punchfork.com/recipe/Beer-Can-Chicken-Simply-Recipes",
    "published": "2009-10-19T14:00:00",
    "source_img": "http://simplyrecipes.com/photos/beer-can-chicken-a.jpg",
    "shortcode": "x42PHv"
  }

List of Publishers

Endpoint:

http://api.punchfork.com/publishers?key={api-key}

Parameters:

• None

Response:

The response is a JSON dictionary containing the following values:

• publishers — Array of publisher records. This lists all recipe publishers on Punchfork.

Example:

$ curl 'http://api.punchfork.com/publishers?key={key}'
{
  "publishers": [
    {
      "name": "Allrecipes",
      "twitter": "Allrecipes",
      "site": "allrecipes.com",
      "num_recipes": 6763,
      "avatar": "http://si0.twimg.com/profile_images/1110173569/AR_Logo_Aug_2010_reasonably_small.png",
      "avg_rating": 28.4673
    },
    ...
  ]
}

Generate Diet Index

This is a Premium API feature.

Endpoint:

http://api.punchfork.com/diet_index?key={api-key}&ingred={ingredients}

Parameters:

• ingred — Recipe ingredients, as a newline-separated list. Each ingredient can be just a name, like "red onion", or free form text that includes units and modifiers, like "1 cup finely chopped red onion".

Response:

The response is a JSON dictionary containing the following values:

• diets — An array of diet terms describing which diets are safe for the input recipe ingredients. The possible diet terms are "vegetarian", "vegan", "gluten free" and "paleo". Diet classification applies to the recipe as a whole, e.g. the recipe is considered vegetarian only if all input ingredients are vegetarian-safe.
• alerts — An array of alert messages from the diet classification of the input ingredients. These are general alerts about unknown ingredients, or warnings about ingredients that are considered conditonally safe for a particular diet. For example, chocolate is considered vegan, but only if it's a particular brand of vegan-safe chocolate; therefore, inputs containing chocolate as an ingredient will receive an alert response saying Possibly vegan: "chocolate". (Note: if no alerts are generated, the alerts field will not be included in the response.)

Example:

Input ingred parameter:

2 cups yellow cornmeal
2 teaspoons baking powder
3/4 to 1 teaspoon fine sea salt
1 large egg, lightly beaten
1 cup water, plus more if needed
1/4 to 1/3 cup mild-flavored vegetable oil for frying

Result:

$ curl 'http://api.punchfork.com/diet_index?key={key}&ingred={ingredients}'
{
  "diets": [
    "gluten free", 
    "vegetarian"
  ]
}

Generate Search Index

This is an Ultra API feature.

Endpoint:

http://api.punchfork.com/search_index?key={api-key}&title={title}&ingred={ingredients}

Parameters:

• title — Recipe title.
• ingred — Recipe ingredients, as a newline-separated list. Each ingredient can be just a name, like "red onion", or free form text that includes units and modifiers, like "1 cup finely chopped red onion".

Response:

The response is a JSON dictionary containing the following values:

• terms — Search index terms for the input recipe. The index includes: (a) the ingredients in the recipe (e.g. "tilapia"), (b) the parent ingredients of each ingredient in the recipe (e.g. "fish"), and (c) the words in the recipe title (e.g. "Best", "Tilapia", "Ever"). Ingredient terms are singularized, canonicalized, and lowercased. Title words ignore punctuation.

Example:

Input title parameter:

Chicken Parmigiana

Input ingred parameter:

1 egg, beaten
2 ounces dry bread crumbs
2 skinless, boneless chicken breast halves
3/4 (16 ounce) jar spaghetti sauce
2 ounces shredded mozzarella cheese
1/4 cup grated Parmesan cheese

Result:

$ curl 'http://api.punchfork.com/search_index?key={key}&title={title}&ingred={ingredients}'
{
  "terms": [
    "bird",
    "bread crumb",
    "cheese",
    "chicken breast",
    "chicken",
    "condiment",
    "dairy",
    "egg",
    "meat",
    "mozzarella",
    "parmesan",
    "parmigiana",
    "poultry",
    "sauce",
    "spaghetti sauce"
  ]
}

Rate Limit Status

Endpoint:

http://api.punchfork.com/rate_limit_status?key={api-key}

Parameters:

• None

Response:

The response is a JSON dictionary containing the following values:

• remaining_calls — The number of remaining API calls allowed today for the given API key. Rate limit counters are reset each day at midnight Pacific US time.

Example:

$ curl 'http://api.punchfork.com/rate_limit_status?key={key}'
{
  "remaining_calls": 423
}