Name: Food & Recipe API - Free Recipe Search & Meal Data
Brand: quotalink
SKU: api-quotalink-food-recipe-api
Availability: InStock
Author: API Market

李乐

## Overview

Food & Recipe API gives you a searchable recipe database behind one base URL: find meals by name, ingredient, category or cuisine, pull a full recipe with measured ingredients and step-by-step instructions, or grab a random dish. Backed by TheMealDB, returned as clean flat JSON.

Search and filter endpoints return lightweight summaries so listings stay fast. When a user picks a dish, `/lookup/{meal_id}` returns the full recipe including a parsed ingredient list, instructions, a source link and a YouTube video where one exists.

## Features

- **Search by name**: partial matches work, so `chicken` returns every chicken dish.
- **Filter by ingredient, category or cuisine**: browse the catalogue along whichever axis your UI needs.
- **Full recipe lookup**: measured ingredients, instructions, thumbnail, source URL and YouTube link.
- **Parsed ingredient list**: ingredient and measure come back as separate fields, already paired, with no string splitting needed.
- **Random meal**: a single call for "surprise me" features.
- **Reference lists**: full category, cuisine and ingredient catalogues with descriptions and images.
- **No provider account needed**: your API.market key is the only credential.

## Use Cases

- **Recipe and meal-planning apps**: search, browse and display full cooking instructions.
- **Grocery and shopping lists**: build a list straight from the parsed ingredient and measure pairs.
- **Food discovery features**: a daily random dish or a "what can I cook with this?" ingredient search.
- **Cuisine exploration**: filter by area to build country or region collections.
- **Voice assistants and chatbots**: read instructions step by step from a lookup response.
- **Content and SEO sites**: generate recipe pages with images, sources and video links.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/food-recipe-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### Meal summary vs full meal

Two shapes appear across the API.

A **summary**, returned by `/search`, `/random` and `/filter`:

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | Pass to `/lookup/{meal_id}` for the full recipe |
| `name` | string | Dish name |
| `thumbnail` | string | Image URL |
| `category` | string | Present on `/search` and `/random`, absent on `/filter` |
| `area` | string | Cuisine, present on `/search` and `/random`, absent on `/filter` |
| `tags` | string | Comma-separated, may be null |

A **full meal**, returned only by `/lookup/{meal_id}`, adds `ingredients`, `instructions`, `source` and `youtube`.

`/filter` deliberately returns the leaner three-field summary, so if your list view shows the cuisine or category you will need a lookup, or use `/search` instead.

### Endpoints

#### GET /search

Finds meals whose name matches the query. Matching is partial and case-insensitive.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | query | string | Yes | Full or partial dish name |

```bash
curl "https://prod.api.market/api/v1/quotalink/food-recipe-api/search?name=arrabiata" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 1,
  "meals": [
    {
      "id": "52771",
      "name": "Spicy Arrabiata Penne",
      "category": "Vegetarian",
      "area": "Italian",
      "tags": "Pasta,Curry",
      "thumbnail": "https://www.themealdb.com/images/media/meals/ustsqw1468250014.jpg"
    }
  ]
}
```

A search with no matches returns `200` with `count: 0` and an empty `meals` array. Omitting `name` returns `400` with `{"error":"name parameter required","success":false}`.

#### GET /random

Returns one randomly selected meal summary. Takes no parameters.

```bash
curl "https://prod.api.market/api/v1/quotalink/food-recipe-api/random" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 1,
  "meals": [
    { "id": "52915", "name": "French Omelette", "category": "Miscellaneous", "area": "France", "tags": "Egg", "thumbnail": "..." }
  ]
}
```

#### GET /lookup/{meal_id}

Returns the complete recipe for one meal.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `meal_id` | path | string | Yes | Meal id from a search, filter or random result |

```bash
curl "https://prod.api.market/api/v1/quotalink/food-recipe-api/lookup/52771" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "meal": {
    "id": "52771",
    "name": "Spicy Arrabiata Penne",
    "category": "Vegetarian",
    "area": "Italian",
    "tags": "Pasta,Curry",
    "thumbnail": "https://www.themealdb.com/images/media/meals/ustsqw1468250014.jpg",
    "instructions": "Bring a large pot of water to a boil ...",
    "source": "https://www.bbcgoodfood.com/recipes/...",
    "youtube": "https://www.youtube.com/watch?v=1IszT_guI08",
    "ingredients": [
      { "ingredient": "penne rigate", "measure": "1 pound" },
      { "ingredient": "olive oil",    "measure": "1/4 cup" }
    ]
  }
}
```

The `ingredients` array is already paired and cleaned, so there are no empty slots to filter out. An unknown id returns `404` with `{"error":"Meal not found","success":false}`.

#### GET /filter

Browses the catalogue by one criterion.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ingredient` | query | string | One of the three | Main ingredient, for example `chicken` |
| `category` | query | string | One of the three | Category name, for example `Seafood` |
| `area` | query | string | One of the three | Cuisine, for example `Italian` |

```bash
curl "https://prod.api.market/api/v1/quotalink/food-recipe-api/filter?category=Seafood" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 84,
  "meals": [
    { "id": "53483", "name": "Acaraje black-eyed pea fritters with shrimp filling", "thumbnail": "..." }
  ]
}
```

**Only one criterion is applied per request.** Passing several does not narrow the results: `ingredient` takes precedence and the others are ignored, so `?ingredient=chicken&area=Italian` returns the same 20 results as `?ingredient=chicken` alone. To combine criteria, filter on one and narrow the rest client-side.

Multi-word ingredients use underscores, for example `chicken_breast`. Calling with no criterion returns `400` with `{"error":"Provide ingredient, category, or area","success":false}`.

#### GET /categories

The full category list with descriptions and images. Takes no parameters.

```bash
curl "https://prod.api.market/api/v1/quotalink/food-recipe-api/categories" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 14,
  "categories": [
    { "name": "Beef", "description": "Beef is the culinary name for meat from cattle ...", "thumbnail": "..." }
  ]
}
```

#### GET /areas

Every cuisine available for `/filter?area=`, as a flat array of strings.

```bash
curl "https://prod.api.market/api/v1/quotalink/food-recipe-api/areas" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 200,
  "areas": ["Afghan", "Albanian", "Algerian", "American", "Argentine"]
}
```

Note the values are demonyms such as `Italian` and `Japanese`, and that is the exact form `/filter?area=` expects.

#### GET /ingredients

The ingredient catalogue with descriptions.

```bash
curl "https://prod.api.market/api/v1/quotalink/food-recipe-api/ingredients" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 100,
  "ingredients": [
    { "name": "Chicken", "type": null, "description": "The chicken is a type of domesticated fowl ..." }
  ]
}
```

#### GET /health

Service liveness. Takes no parameters and is useful for monitoring.

```json
{ "service": "food-recipe-api", "status": "ok" }
```

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | Required parameter or the `x-api-market-key` header is missing | Send `name`, or one filter criterion, and check headers |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `404` | Meal id not found | Use an id returned by search, filter or random |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `5xx` | Upstream recipe database error | Retry with exponential backoff |

## Rate Limits

Both plans allow up to **10 requests per second**. Quotas apply per billing period:

- **FREE**: 100 API units, hard limit. Requests are rejected once the quota is spent.
- **PRO**: 10,000 API units per month, hard limit.

Every endpoint costs one unit per request.

## Error Handling

Errors return JSON with an `error` field and `success: false`:

```json
{ "error": "name parameter required", "success": false }
```

```json
{ "error": "Meal not found", "success": false }
```

An empty result set is not an error. `/search` and `/filter` return `200` with `count: 0`, so check `count` before rendering a list.

## Implementation Guide

### Example Code

```python
import requests

BASE = "https://prod.api.market/api/v1/quotalink/food-recipe-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}

def shopping_list(dish):
    hits = requests.get(f"{BASE}/search", params={"name": dish},
                        headers=HEADERS, timeout=15).json()
    if not hits["count"]:
        return None
    meal_id = hits["meals"][0]["id"]
    meal = requests.get(f"{BASE}/lookup/{meal_id}",
                        headers=HEADERS, timeout=15).json()["meal"]
    return meal["name"], [
        f"{i['measure']} {i['ingredient']}" for i in meal["ingredients"]
    ]

name, items = shopping_list("arrabiata")
print(name)
for line in items:
    print(" -", line)
```

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/food-recipe-api";
const headers = { "x-api-market-key": process.env.API_MARKET_KEY };

async function browseCuisine(area) {
  const res = await fetch(`${BASE}/filter?area=${encodeURIComponent(area)}`, {
    headers,
  });
  if (!res.ok) throw new Error(`Filter failed: ${res.status}`);
  const { count, meals } = await res.json();
  if (!count) return [];
  return meals.map((m) => ({ id: m.id, name: m.name, image: m.thumbnail }));
}

console.log(await browseCuisine("Italian"));
```

### Performance Optimization

- Cache `/categories`, `/areas` and `/ingredients` for a long time. They are reference data that changes rarely, and caching removes them from your quota entirely.
- Cache lookups by meal id. A recipe does not change, so a long TTL is safe.
- Use `/search` rather than `/filter` when your list view needs the category or cuisine, since the filter summary omits both and would force an extra lookup per row.
- Fetch full recipes lazily, when the user opens a dish, instead of pre-fetching every row in a list.
- Stay within 10 requests per second and queue bulk imports rather than firing them in parallel.

## FAQ

**Do I need an account with QuotaLink or TheMealDB to use this API?**

No. Your API.market key is the only credential required.

**Can I filter by ingredient and cuisine at the same time?**

No. Only one criterion is applied per request, and `ingredient` takes precedence over the others. Filter on one and narrow the rest in your own code.

**Why does `/filter` not return the category or cuisine?**

It returns a leaner summary with only `id`, `name` and `thumbnail`. Use `/search`, or call `/lookup/{meal_id}`, when you need those fields.

**How do I search for an ingredient with a space in it?**

Use an underscore, for example `chicken_breast`.

**Do I have to unpack ingredient and measurement strings myself?**

No. The `ingredients` array on a lookup already pairs each `ingredient` with its `measure`, with empty entries removed.

**Does every recipe have a video?**

No. `youtube` and `source` can be null, so check before rendering a link.

**What does an empty result look like?**

A `200` with `count: 0` and an empty array, not an error.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Search thousands of recipes by name, ingredient, or cuisine. Free API for cooking apps, food blogs, and meal planning tools.