Recipe Finder

Recipe Finder Skill

Find recipes, get nutrition information, and create meal plans using free recipe APIs. Supports searching by ingredients, dietary restrictions, cuisine type, and more.

When to Use

• User asks for recipe suggestions
• User wants to know what to cook with specific ingredients
• User has dietary restrictions (vegetarian, gluten-free, keto, etc.)
• User asks about nutrition or calories in a recipe
• User wants meal planning help
• User asks about cooking instructions or techniques
• User asks "what can I make with..."

Available Operations

1. Recipe Search: Find recipes by keyword, ingredient, or cuisine 2. Ingredient-Based Search: "What can I make with chicken and broccoli?" 3. Dietary Filtering: Filter by diet (vegan, keto, paleo) or intolerances 4. Nutrition Analysis: Get calorie and nutrient breakdown 5. Random Recipe: Get a random recipe for inspiration 6. Recipe Details: Get full instructions, ingredients, and nutrition

Instructions

When a user asks about recipes or cooking:

Step 1: Understand the Query

Identify what the user needs:

• Ingredient-based: "What can I make with [ingredients]?"
• Cuisine search: "Give me Italian recipes"
• Dietary needs: "Keto dinner ideas"
• Specific dish: "How do I make chicken parmesan?"
• Nutrition focused: "Low calorie lunch ideas"

Step 2: Load API Reference

ALWAYS read references/api_reference.md before making API calls. The APIs have specific parameter formats.

Step 3: Choose the Right API

Option A: TheMealDB (Simpler, Completely Free)

• Good for: Basic recipe search, random recipes, category browsing
• URL: https://www.themealdb.com/api/json/v1/1/
• No API key needed (use "1" as the key)

Option B: Spoonacular (More Powerful, Free Tier)

• Good for: Ingredient search, nutrition, dietary filters
• Requires API key (free tier: 150 points/day)
• More detailed data but limited calls

Step 4: Make the API Call

TheMealDB Example (search by name):

https://www.themealdb.com/api/json/v1/1/search.php?s=chicken

Spoonacular Example (search by ingredients):

https://api.spoonacular.com/recipes/findByIngredients?ingredients=chicken,broccoli&number=5&apiKey=YOUR_KEY

Step 5: Present Results

Format recipes clearly with:

• Recipe name
• Brief description or cuisine type
• Key ingredients
• Cooking time (if available)
• Dietary info (vegetarian, gluten-free, etc.)
• Link to full recipe or instructions

Dietary Restriction Mappings

Cuisine Types

TheMealDB categories: American, British, Canadian, Chinese, Croatian, Dutch, Egyptian, Filipino, French, Greek, Indian, Irish, Italian, Jamaican, Japanese, Kenyan, Malaysian, Mexican, Moroccan, Polish, Portuguese, Russian, Spanish, Thai, Tunisian, Turkish, Vietnamese

Resources

ALWAYS read these before making API calls:

• references/api_reference.md - Complete API documentation for both services
• references/dietary_guide.md - Detailed dietary restriction information

Examples

Example 1: Ingredient-Based Search

User asks: "What can I make with chicken, garlic, and lemon?"

1. Load API reference 2. Use TheMealDB search or Spoonacular findByIngredients 3. Return 3-5 recipe suggestions with names and key details

Example 2: Dietary Restriction

User asks: "I need gluten-free dinner ideas"

1. Load API reference 2. Use Spoonacular with intolerances=gluten 3. Or use TheMealDB and filter results manually 4. Highlight that recipes are gluten-free in response

Example 3: Quick Recipe

User asks: "Give me an easy pasta recipe"

1. Search TheMealDB for "pasta" 2. Pick a result with simple ingredients 3. Provide full recipe with ingredients and instructions

Example 4: Nutrition Query

User asks: "How many calories in chicken alfredo?"

1. Search for chicken alfredo recipe 2. Use Spoonacular nutrition endpoint or estimate 3. Provide calorie and macro breakdown per serving

Example 5: Random Inspiration

User asks: "What should I cook tonight?"

1. Use TheMealDB random endpoint: /random.php 2. Present the recipe with ingredients and instructions 3. Offer to find alternatives if they don't like it

Notes

• TheMealDB is completely free with no limits - prefer it for basic searches
• Spoonacular free tier is 150 points/day (searches cost ~1 point each)
• Always check dietary restrictions before recommending recipes
• Cooking times are estimates - actual time varies by skill level
• Ingredient quantities may need scaling based on servings
• When nutrition data isn't available, note that it's an estimate

Recipe API Reference

This skill uses two free recipe APIs: TheMealDB (simpler, unlimited) and Spoonacular (more powerful, limited free tier).

---

TheMealDB API

Completely free, no signup required. Good for basic recipe searches.

Base URL

https://www.themealdb.com/api/json/v1/1

Note: Use 1 as the API key for the free tier.

---

Search Endpoints

Search by Name

GET /search.php?s={query}

Search recipes by name.

https://www.themealdb.com/api/json/v1/1/search.php?s=chicken

Search by First Letter

GET /search.php?f={letter}

Get all recipes starting with a letter.

https://www.themealdb.com/api/json/v1/1/search.php?f=c

Lookup by ID

GET /lookup.php?i={id}

Get full recipe details by ID.

https://www.themealdb.com/api/json/v1/1/lookup.php?i=52772

Random Recipe

GET /random.php

Get a single random recipe.

https://www.themealdb.com/api/json/v1/1/random.php

---

Filter Endpoints

Filter by Ingredient

GET /filter.php?i={ingredient}

Find recipes containing a specific ingredient.

https://www.themealdb.com/api/json/v1/1/filter.php?i=chicken_breast

Note: Returns only id, name, and thumbnail. Use lookup for full details.

Filter by Category

GET /filter.php?c={category}

Filter by meal category.

https://www.themealdb.com/api/json/v1/1/filter.php?c=Seafood

Categories: Beef, Breakfast, Chicken, Dessert, Goat, Lamb, Miscellaneous, Pasta, Pork, Seafood, Side, Starter, Vegan, Vegetarian

Filter by Area/Cuisine

GET /filter.php?a={area}

Filter by cuisine/country.

https://www.themealdb.com/api/json/v1/1/filter.php?a=Italian

Areas: American, British, Canadian, Chinese, Croatian, Dutch, Egyptian, Filipino, French, Greek, Indian, Irish, Italian, Jamaican, Japanese, Kenyan, Malaysian, Mexican, Moroccan, Polish, Portuguese, Russian, Spanish, Thai, Tunisian, Turkish, Unknown, Vietnamese

---

List Endpoints

List All Categories

GET /categories.php

Get all meal categories with descriptions.

List Category Names

GET /list.php?c=list

Get just category names.

List All Areas

GET /list.php?a=list

Get all cuisine areas.

List All Ingredients

GET /list.php?i=list

Get all available ingredients.

---

Response Format

Full Recipe Object

{
  "meals": [
    {
      "idMeal": "52772",
      "strMeal": "Teriyaki Chicken Casserole",
      "strCategory": "Chicken",
      "strArea": "Japanese",
      "strInstructions": "Preheat oven to 350...",
      "strMealThumb": "https://www.themealdb.com/images/media/meals/wvpsxx1468256321.jpg",
      "strYoutube": "https://www.youtube.com/watch?v=4aZr5hZXP_s",
      "strIngredient1": "soy sauce",
      "strIngredient2": "water",
      "strIngredient3": "brown sugar",
      "strMeasure1": "3/4 cup",
      "strMeasure2": "1/2 cup",
      "strMeasure3": "1/4 cup",
      "strSource": "https://example.com/recipe",
      "strTags": "Meat,Casserole"
    }
  ]
}

Note: Ingredients and measures are in separate numbered fields (strIngredient1-20, strMeasure1-20). Empty ingredients should be ignored.

---

Spoonacular API

More powerful with nutrition data and dietary filters. Free tier: 150 points/day.

Base URL

https://api.spoonacular.com

Authentication

All requests require apiKey parameter:

?apiKey=YOUR_API_KEY

---

Recipe Search

Complex Search

GET /recipes/complexSearch

Powerful search with many filters.

Example:

https://api.spoonacular.com/recipes/complexSearch?query=pasta&diet=vegetarian&maxReadyTime=30&number=5&apiKey=KEY

Search by Ingredients

GET /recipes/findByIngredients

Find recipes using specific ingredients.

Example:

https://api.spoonacular.com/recipes/findByIngredients?ingredients=chicken,garlic,onion&number=5&apiKey=KEY

Random Recipes

GET /recipes/random

Get random recipes.

Example:

https://api.spoonacular.com/recipes/random?number=1&tags=vegetarian,main+course&apiKey=KEY

---

Recipe Details

Get Recipe Information

GET /recipes/{id}/information

Get full recipe details including nutrition.

Example:

https://api.spoonacular.com/recipes/716429/information?includeNutrition=true&apiKey=KEY

Get Similar Recipes

GET /recipes/{id}/similar

Find recipes similar to a given one.

https://api.spoonacular.com/recipes/716429/similar?number=5&apiKey=KEY

---

Nutrition Endpoints

Nutrition by ID

GET /recipes/{id}/nutritionWidget.json

Get nutrition breakdown for a recipe.

https://api.spoonacular.com/recipes/716429/nutritionWidget.json?apiKey=KEY

Analyze Recipe

POST /recipes/analyze

Analyze a recipe's nutrition from ingredients.

{
  "title": "Spaghetti Carbonara",
  "servings": 4,
  "ingredients": [
    "400g spaghetti",
    "200g pancetta",
    "4 egg yolks",
    "100g parmesan"
  ]
}

---

Diet & Intolerance Values

Diets

Intolerances

---

Cuisine Types

african, american, british, cajun, caribbean, chinese, eastern european, european, french, german, greek, indian, irish, italian, japanese, jewish, korean, latin american, mediterranean, mexican, middle eastern, nordic, southern, spanish, thai, vietnamese

---

Meal Types

---

Point Costs (Free Tier)

The free tier has 150 points/day. Approximate costs:

Tip: Use TheMealDB for basic searches to save Spoonacular points for nutrition queries.

---

Error Responses

---

Building Recipe Image URLs

TheMealDB

Images are included in responses as strMealThumb.

Spoonacular

Build image URLs:

https://spoonacular.com/recipeImages/{id}-312x231.jpg

Sizes: 90x90, 240x150, 312x231, 480x360, 556x370, 636x393

Dietary Restrictions Guide

This guide helps you understand common dietary restrictions and how to filter recipes appropriately.

---

Quick Reference Table

---

Detailed Diet Explanations

Vegetarian

Excludes:

• All meat (beef, pork, lamb, poultry)
• Fish and seafood
• Animal-derived gelatin

Includes:

• Eggs (ovo-vegetarian)
• Dairy (lacto-vegetarian)
• Honey
• Plant-based foods

Common substitutions:

• Meat → Tofu, tempeh, seitan, legumes
• Gelatin → Agar-agar
• Chicken broth → Vegetable broth

---

Vegan

Excludes:

• All meat and fish
• Dairy (milk, cheese, butter, cream)
• Eggs
• Honey
• Gelatin
• Some sugars (processed with bone char)

Includes:

• All plant-based foods
• Plant milks (oat, almond, soy)
• Nutritional yeast

Common substitutions:

• Butter → Vegan butter, coconut oil
• Milk → Oat milk, almond milk
• Cheese → Nutritional yeast, vegan cheese
• Eggs → Flax eggs, chia eggs, aquafaba
• Honey → Maple syrup, agave

---

Gluten-Free

Excludes:

• Wheat (bread, pasta, most baked goods)
• Barley
• Rye
• Spelt
• Many sauces (soy sauce contains wheat)
• Beer (unless gluten-free)

Includes:

• Rice
• Corn
• Quinoa
• Oats (if certified gluten-free)
• Potatoes
• All meats, fish, dairy, eggs
• Most vegetables and fruits

Hidden gluten sources:

• Soy sauce → Use tamari (gluten-free soy sauce)
• Worcestershire sauce
• Some salad dressings
• Imitation crab
• Malt vinegar

Common substitutions:

• Pasta → Rice pasta, chickpea pasta
• Flour → Almond flour, rice flour, GF flour blend
• Bread → Gluten-free bread
• Soy sauce → Tamari or coconut aminos

---

Dairy-Free

Excludes:

• Milk
• Cheese
• Butter
• Cream
• Yogurt
• Ice cream
• Whey and casein (hidden in many products)

Includes:

• Plant milks
• Coconut cream
• Vegan cheeses
• All meats, fish, eggs

Hidden dairy sources:

• Many breads contain milk
• Some chips contain whey
• Margarine may contain dairy
• "Non-dairy" creamer may contain casein

Common substitutions:

• Milk → Oat milk, coconut milk, almond milk
• Butter → Olive oil, coconut oil, vegan butter
• Cream → Coconut cream, cashew cream
• Cheese → Nutritional yeast, vegan cheese

---

Ketogenic (Keto)

Macronutrient Target:

• 70-75% fat
• 20-25% protein
• 5-10% carbs (usually <50g/day, strict <20g)

Excludes:

• Sugar and sweeteners (except stevia, erythritol)
• Grains (bread, rice, pasta)
• Most fruits (except berries in moderation)
• Starchy vegetables (potatoes, corn)
• Legumes (beans, lentils)

Includes:

• Meat and fatty fish
• Eggs
• Cheese and cream
• Nuts and seeds
• Low-carb vegetables (leafy greens, broccoli)
• Healthy oils (olive, coconut, avocado)
• Avocados

Keto-friendly recipes typically feature:

• High fat content
• Moderate protein
• Very low net carbs
• Cauliflower as rice/potato substitute

---

Paleo

Philosophy: Eat like our ancestors (hunter-gatherers)

Excludes:

• Grains (wheat, rice, oats)
• Legumes (beans, lentils, peanuts)
• Dairy
• Refined sugar
• Processed foods
• Vegetable oils (canola, soybean)

Includes:

• Meat (preferably grass-fed)
• Fish and seafood
• Eggs
• Vegetables
• Fruits
• Nuts and seeds
• Healthy fats (olive oil, coconut oil, avocado)

Common substitutions:

• Pasta → Zucchini noodles, spaghetti squash
• Rice → Cauliflower rice
• Flour → Almond flour, coconut flour
• Sugar → Honey, maple syrup (in moderation)

---

Low FODMAP

For: People with IBS or digestive issues

FODMAP stands for: Fermentable Oligosaccharides, Disaccharides, Monosaccharides, and Polyols

High FODMAP foods to avoid:

• Onions and garlic
• Wheat
• Many fruits (apples, pears, watermelon)
• Dairy with lactose
• Legumes
• Some sweeteners (honey, high fructose corn syrup)

Low FODMAP alternatives:

• Garlic-infused oil (instead of garlic)
• Green parts of scallions
• Lactose-free dairy
• Gluten-free grains

---

Food Allergies vs. Intolerances

Allergies (Immune Response)

• Can be life-threatening
• Complete avoidance required
• Common: peanuts, tree nuts, shellfish, fish, eggs, milk, wheat, soy

Intolerances (Digestive Issues)

• Uncomfortable but not dangerous
• Small amounts may be tolerable
• Common: lactose, gluten, FODMAPs

When user mentions an allergy, treat it seriously and ensure complete exclusion.

---

The "Big 8" Food Allergens

These account for 90% of food allergies:

1. Milk - Use intolerances=dairy 2. Eggs - Use intolerances=egg 3. Fish - Use intolerances=seafood 4. Shellfish - Use intolerances=shellfish 5. Tree Nuts - Use intolerances=tree nut 6. Peanuts - Use intolerances=peanut 7. Wheat - Use intolerances=wheat 8. Soybeans - Use intolerances=soy

---

Combining Restrictions

Users often have multiple restrictions. Combine filters:

Vegan + Gluten-Free:

diet=vegan&intolerances=gluten

Keto + Dairy-Free:

diet=ketogenic&intolerances=dairy

Multiple Allergies:

intolerances=peanut,tree nut,dairy

---

Tips for Recipe Recommendations

1. Always clarify if restrictions are preferences vs. allergies 2. Check all ingredients - hidden allergens are common 3. Offer substitutions when a recipe almost fits 4. Note cross-contamination risks for severe allergies 5. Respect cultural/religious diets (halal, kosher) even if not in API

---

Common Substitution Cheat Sheet