# FlavorFetch API - Recipe Extraction from YouTube & Blogs ## 📖 Overview FlavorFetch is an AI-powered recipe extraction API that transforms cooking content into structured, normalized recipe data. Extract recipes from YouTube cooking videos or recipe blog URLs and receive consistent JSON with ingredients, instructions, cooking times, nutrition, and more. Built for developers who need reliable recipe data without the complexity of building custom scrapers. ## ✨ Key Features - **AI-Powered Extraction** - Advanced AI understands recipe structure from any source format - **YouTube Video Extraction** - Extract recipes from cooking video transcripts with precise timestamps - **Recipe Blog Support** - Works with recipe blogs and cooking websites - **HTML & Text Content Processing** - Submit HTML or plain text directly for offline or pre-fetched content - **Structured Output** - Normalized JSON with ingredients, instructions, times, yields, and nutrition - **Smart Navigation** - Timestamps for YouTube videos, text fragments for blog posts - **Measurement Systems** - Support for both metric and imperial units - **Multi-Language** - Process recipes in multiple languages ## 🎯 Use Cases - **Recipe Aggregator Apps** - Build comprehensive recipe databases from multiple sources - **Meal Planning Applications** - Help users discover and organize recipes for weekly planning - **Cooking Assistants & Chatbots** - Power conversational interfaces with structured recipe data - **Content Analysis Tools** - Analyze recipe trends, ingredients, and cooking techniques - **Recipe Databases** - Populate your database with normalized recipe content - **Cooking Education Platforms** - Create interactive learning experiences with video timestamps ## 🚀 Quick Start ### 1. Subscribe on RapidAPI Get your API access through RapidAPI marketplace ### 2. Make Your First Request ```javascript const options = { method: 'POST', headers: { 'content-type': 'application/json', 'X-RapidAPI-Key': 'YOUR_RAPIDAPI_KEY', 'X-RapidAPI-Host': 'YOUR_RAPIDAPI_HOST' }, body: JSON.stringify({ url: 'https://www.youtube.com/watch?v=vI6MFvxrRnU' }) }; const response = await fetch('https://YOUR_RAPIDAPI_HOST/api/v1/extract', options); const data = await response.json(); console.log(data); ``` ### 3. Get Structured Recipe Data ```json { "success": true, "title": "Classic Chocolate Chip Cookies", "description": "The best chocolate chip cookies you'll ever make", "ingredients": [ { "item": "all-purpose flour", "quantity": "2", "unit": "cups" } ], "instructions": [ { "step": 1, "text": "Preheat oven to 375°F", "navigation": { "timestamp": "0:45", "timestamp_seconds": 45, "url": "https://www.youtube.com/watch?v=vI6MFvxrRnU&t=45s" } } ], "prepTime": "15 minutes", "cookTime": "12 minutes", "totalTime": "27 minutes", "servings": 24, "nutrition": { "calories": "150", "protein": "2g", "carbohydrates": "20g", "fat": "7g" } } ``` ## ⚡ Why Choose FlavorFetch? ### 🤖 AI-Powered Extraction FlavorFetch uses AI specifically designed for recipe content, not generic web scraping. It understands recipe structure including ingredients, instructions, cooking times, and yields, and handles recipe-specific formats from both videos and blogs. Our AI adapts to different content formats automatically, eliminating the need for site-specific parsers. ### 🎯 Purpose-Built for Recipes Unlike generic web scrapers that require constant maintenance, FlavorFetch is built specifically for recipe extraction and understands the nuances of cooking content across different platforms and formats. ### 📹 YouTube Video Support Extract recipes from YouTube cooking videos via transcripts with precise timestamps for each instruction step. Enable deep linking directly to relevant video moments. This level of YouTube integration is unique to FlavorFetch. ### 🔄 Normalized Output Converts diverse formats into consistent, structured data. Get the same schema whether your source is YouTube, a major recipe site, or a personal blog. Eliminates the need for site-specific parsing logic and saves weeks of development time. ### 🌍 Multi-Source Flexibility - Works with major recipe sites and personal cooking blogs - Handles unknown sites via AI-powered generic extractor - Accepts HTML or plain text content for offline processing - Three input methods: URL, content, or both ### 🎨 Developer-Friendly - Clean, predictable JSON structure - Detailed error messages with specific error codes - Comprehensive documentation and code examples - No complex authentication flows (handled by RapidAPI) ### ⚖️ Legal Clarity - Clear terms about user responsibility for compliance - Transparent about data sources (publicly available content only) - You are responsible for ensuring your use complies with platform terms - You stay in control of your legal obligations ### 🚀 Production-Ready - Battle-tested extraction logic handling real-world recipe diversity - Gracefully handles edge cases and malformed data - Returns partial results when full extraction isn't possible - Built for the messy reality of cooking content on the internet ## 📡 Available Endpoints *Access these through RapidAPI's base URL* ### `POST /api/v1/extract` Extract recipe data from a URL, HTML content, or plain text. **Request Body:** - `url` (string, optional) - YouTube video URL or recipe blog URL - `content` (string, optional) - HTML or plain text content to extract from - `preferences` (object, optional) - Extraction preferences *Note: Either `url` or `content` must be provided.* ### `GET /api/v1/health` Check API service health status. ## 💡 Request Examples (JavaScript) ### Extract from YouTube Video ```javascript const options = { method: 'POST', headers: { 'content-type': 'application/json', 'X-RapidAPI-Key': 'YOUR_RAPIDAPI_KEY', 'X-RapidAPI-Host': 'YOUR_RAPIDAPI_HOST' }, body: JSON.stringify({ url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ', preferences: { measurement_system: 'metric', language: 'en' } }) }; try { const response = await fetch('https://YOUR_RAPIDAPI_HOST/api/v1/extract', options); const recipe = await response.json(); if (recipe.success) { console.log('Recipe:', recipe.title); console.log('Ingredients:', recipe.ingredients); } else { console.log('Extraction failed or no recipe found'); } } catch (error) { console.error('Error:', error); } ``` ### Extract from Recipe Blog ```javascript const options = { method: 'POST', headers: { 'content-type': 'application/json', 'X-RapidAPI-Key': 'YOUR_RAPIDAPI_KEY', 'X-RapidAPI-Host': 'YOUR_RAPIDAPI_HOST' }, body: JSON.stringify({ url: 'https://example-recipe-blog.com/best-pasta-recipe', preferences: { measurement_system: 'imperial', language: 'en' } }) }; const response = await fetch('https://YOUR_RAPIDAPI_HOST/api/v1/extract', options); const recipe = await response.json(); ``` ### Extract from HTML or Plain Text Content ```javascript const htmlContent = ` <html> <body>

Homemade Pizza

2 cups flour
1 tsp yeast

Mix ingredients
Let dough rise

</body> </html> `; const options = { method: 'POST', headers: { 'content-type': 'application/json', 'X-RapidAPI-Key': 'YOUR_RAPIDAPI_KEY', 'X-RapidAPI-Host': 'YOUR_RAPIDAPI_HOST' }, body: JSON.stringify({ content: htmlContent, preferences: { measurement_system: 'metric' } }) }; const response = await fetch('https://YOUR_RAPIDAPI_HOST/api/v1/extract', options); const recipe = await response.json(); ``` ### Using RapidAPI SDK ```javascript import axios from 'axios'; const extractRecipe = async (url) => { const options = { method: 'POST', url: 'https://YOUR_RAPIDAPI_HOST/api/v1/extract', headers: { 'content-type': 'application/json', 'X-RapidAPI-Key': 'YOUR_RAPIDAPI_KEY', 'X-RapidAPI-Host': 'YOUR_RAPIDAPI_HOST' }, data: { url: url, preferences: { measurement_system: 'metric', language: 'en' } } }; try { const response = await axios.request(options); return response.data; } catch (error) { console.error(error); throw error; } }; // Usage const recipe = await extractRecipe('https://www.youtube.com/watch?v=example'); console.log(recipe); ``` ## 📦 Response Structure ### Successful Response ```json { "success": true, "title": "Recipe Title", "description": "Recipe description", "ingredients": [ { "item": "ingredient name", "quantity": "2", "unit": "cups", "notes": "optional preparation notes" } ], "instructions": [ { "step": 1, "text": "Instruction text", "navigation": { "timestamp": "1:30", "timestamp_seconds": 90, "url": "https://youtube.com/watch?v=id&t=90s" } } ], "prepTime": "15 minutes", "cookTime": "30 minutes", "totalTime": "45 minutes", "servings": 4, "difficulty": "easy", "cuisine": "Italian", "category": "Main Course", "tags": ["dinner", "pasta"], "nutrition": { "calories": "350", "protein": "15g", "carbohydrates": "45g", "fat": "12g", "fiber": "3g", "sugar": "5g" }, "sourceUrl": "https://original-source-url.com", "image": "https://image-url.com/recipe.jpg" } ``` ### Key Fields Explained - **`success`** (boolean) - Indicates if recipe extraction was successful. Always check this field. - **`title`** (string) - Recipe name - **`description`** (string) - Brief recipe description - **`ingredients`** (array) - List of ingredients with quantity, unit, and optional notes - **`instructions`** (array) - Step-by-step cooking instructions with navigation - **`prepTime`** / **`cookTime`** / **`totalTime`** (string) - Time estimates in human-readable format - **`servings`** (number) - Number of servings the recipe yields - **`difficulty`** (string) - Difficulty level: "easy", "medium", "hard" - **`nutrition`** (object) - Nutritional information per serving - **`sourceUrl`** (string) - Original URL of the recipe ### Navigation Object Differences **YouTube Videos:** ```json { "timestamp": "2:30", "timestamp_seconds": 150, "url": "https://youtube.com/watch?v=abc&t=150s" } ``` **Recipe Blogs:** ```json { "text_fragment": "Preheat the oven", "text_start_offset": 450, "url": "https://blog.com/recipe#:~:text=Preheat%20the%20oven" } ``` ### Extraction Failure Response Even with HTTP 200 status, extraction may fail: ```json { "success": false, "title": null, "ingredients": [], "instructions": [] } ``` **Always check the `success` field** to determine if a recipe was found. ## ⚠️ Error Handling ### HTTP Status Codes - **200** - Request processed (check `success` field for extraction result) - **400** - Bad request (invalid parameters or missing required fields) - **401** - Unauthorized (invalid or missing RapidAPI key) - **405** - Method not allowed (use POST for /extract, GET for /health) - **429** - Rate limit exceeded - **500** - Internal server error ### Error Response Format ```json { "error": "Error message describing what went wrong", "code": "ERROR_CODE" } ``` ### Common Error Codes - `MISSING_URL_OR_CONTENT` - Neither url nor content provided - `INVALID_URL` - URL format is invalid - `INVALID_JSON` - Request body is not valid JSON - `MISSING_API_KEY` - API key not provided - `INVALID_API_KEY` - API key is invalid - `RATE_LIMIT_EXCEEDED` - Rate limit exceeded - `METHOD_NOT_ALLOWED` - Wrong HTTP method used - `INTERNAL_ERROR` - Server error occurred ### Handling Extraction Failures ```javascript const response = await fetch('https://YOUR_RAPIDAPI_HOST/api/v1/extract', options); const data = await response.json(); if (response.status === 200) { if (data.success) { // Recipe extracted successfully console.log('Recipe found:', data.title); processRecipe(data); } else { // Extraction attempted but no recipe found console.log('No recipe found at this URL'); showNoRecipeMessage(); } } else { // HTTP error occurred console.error('Error:', data.error, data.code); handleError(data); } ``` ## 🎛️ Request Parameters ### `url` (string, optional) YouTube video URL or recipe blog URL to extract from. **Examples:** - `https://www.youtube.com/watch?v=VIDEO_ID` - `https://youtu.be/VIDEO_ID` - `https://recipe-blog.com/amazing-cookies` ### `content` (string, optional) HTML or plain text content to extract recipe from. Useful for offline processing or when you've already fetched the page. Accepts both structured HTML and unstructured plain text. **Note:** Either `url` or `content` must be provided, but not both. ### `preferences` (object, optional) Customize extraction behavior. #### `preferences.measurement_system` (string) Preferred measurement system for ingredients. - `"metric"` - Use metric units (grams, liters, celsius) - `"imperial"` - Use imperial units (cups, ounces, fahrenheit) **Default:** `"metric"` #### `preferences.language` (string) Expected language of the content. ISO 639-1 language code. **Examples:** `"en"`, `"es"`, `"fr"`, `"de"`, `"it"` **Default:** `"en"` ### Full Request Example ```json { "url": "https://www.youtube.com/watch?v=example", "preferences": { "measurement_system": "imperial", "language": "en" } } ``` ## 📝 Important Legal Notice **User Responsibility:** You are solely responsible for ensuring your use of this API complies with all applicable laws and regulations, including: - YouTube's Terms of Service and other platform terms - Applicable copyright laws - Data protection regulations (GDPR, CCPA, etc.) - Your jurisdiction's laws and regulations **What We Do:** FlavorFetch extracts publicly available data that platforms make accessible through normal viewing. We process transcripts, metadata, HTML content, and plain text that is openly available. **What We Don't Do:** We do not assume legal responsibility for your use of extracted data. Any legal issues, claims, or disputes arising from your use of this API are your sole responsibility. **Compliance:** Before using extracted content, ensure you have necessary permissions, licenses, or authorizations. Your use must not infringe on any third-party rights or violate platform terms of service. **Full Terms:** For complete legal information, see our Terms of Service at https://flavorfetch.dev/tos --- *Built with ❤️ for developers who love cooking (or developers building for people who love cooking)*