Name: Nutrition Facts API: Calories and Macros From USDA Data
Brand: tidydata
SKU: api-tidydata-nutrition-facts
Availability: InStock
Author: API Market

TidyData

# Nutrition Facts API

## Overview

Nutrition Facts API gives calories and 36 nutrients for 7,793 generic foods from USDA FoodData Central (SR Legacy, public domain CC0). It has four endpoints that work together. GET /v1/nutrition/search finds foods by English name and returns each match's fdcId, name, category and per 100 g calories, protein, fat and carbohydrates. GET /v1/nutrition/food/{fdcId} returns the full set of 36 nutrients per 100 g, scales them to any weight with grams, and lists common portions such as a cup, slice or piece. GET /v1/nutrition/calculate takes a list of foods with gram amounts and returns per item macros and total nutrients for a recipe or meal, and GET /v1/nutrition/categories lists the 25 food categories you can use as a search filter.

It is built for diet and fitness apps, recipe sites that show nutrition per serving, meal planners, calorie counters, food delivery menus, and health chatbots or AI agents that need real nutrient numbers instead of estimates. Nutrients include energy, macros, fiber, sugars, fat types, cholesterol, minerals, vitamins A, C, D, E, K and the B group, choline, caffeine and alcohol, each with its unit. Search prefers the common form of a food: in our test "eggs" matched whole raw egg and the meal of 100 g eggs, 50 g oats and 200 g whole milk totalled 454.5 kcal in 809 ms. The API runs on a global edge network (Cloudflare Workers) and needs only the x-api-market-key header.

## Features

*   **Four endpoints**: Search, food details, recipe or meal totals, and the list of food categories.
*   **36 nutrients**: Calories, macros, fiber, sugars, fat types, minerals, vitamins, choline, caffeine and alcohol, each with amount and unit.
*   **Any amount**: Add grams to a food lookup to get nutrients scaled to that weight alongside the per 100 g values.
*   **Portion sizes**: Food details include common portions with their gram weight, such as 1 cup sliced or 1 large.
*   **Recipe calculator**: Send food:grams pairs and get the matched food for each item plus combined totals.
*   **Public domain data**: USDA FoodData Central SR Legacy, released as CC0.
*   **Rate limit**: Every plan allows up to 10 requests per second.

## Use Cases

*   **Diet and fitness apps**: Log foods by name and weight and show calories and macros for each meal.
*   **Recipe sites**: Calculate nutrition for a whole recipe and divide it per serving.
*   **Meal planners**: Build daily plans that hit calorie and protein targets using real nutrient values.
*   **Food delivery menus**: Show estimated calories and macros next to dishes based on their ingredients.
*   **Health chatbots and AI agents**: Give assistants a tool that returns USDA numbers instead of guessed nutrition facts.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/tidydata/nutrition-facts
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Search foods

Finds foods by English name, optionally within a category, and returns up to 50 matches with fdcId, category and per 100 g calories, protein, fat and carbohydrates. Use it to find the fdcId for a full lookup.

**Method:** `GET`

**Endpoint:** `/v1/nutrition/search`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `q` | query | Food name in English | string | Yes | - | - |
| `category` | query | Optional category filter (see /categories) | string | No | - | - |
| `limit` | query | 1-50 | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/nutrition-facts/v1/nutrition/search?q=chicken%20breast&category=&limit=10" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "query": "chicken breast",
  "count": 10,
  "foods": [
    {
      "fdcId": 171477,
      "name": "Chicken, broilers or fryers, breast, meat only, cooked, roasted",
      "category": "Poultry Products",
      "per100g": {
        "energy_kcal": 165,
        "protein_g": 31,
        "fat_g": 3.57,
        "carbohydrates_g": 0
      }
    },
    {
      "fdcId": 174608,
      "name": "Chicken breast, roll, oven-roasted",
      "category": "Sausages and Luncheon Meats",
      "per100g": {
        "energy_kcal": 134,
        "protein_g": 14.6,
        "fat_g": 7.65,
        "carbohydrates_g": 1.79
      }
    },
    {
      "fdcId": 172963,
      "name": "Chicken breast, oven-roasted, fat-free, sliced",
      "category": "Sausages and Luncheon Meats",
      "per100g": {
        "energy_kcal": 79,
        "protein_g": 16.8,
        "fat_g": 0.39,
        "carbohydrates_g": 2.17
      }
    }
  ],
  "source": "USDA FoodData Central, SR Legacy (public domain, CC0)"
}
```

#### 2. Get food details

Returns all 36 nutrients per 100 g for one food, its common portion sizes and, when grams is set, the nutrients scaled to that weight.

**Method:** `GET`

**Endpoint:** `/v1/nutrition/food/{fdcId}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `fdcId` | path | Food id from search | string | Yes | - | - |
| `grams` | query | Optional amount in grams to scale nutrients | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/nutrition-facts/v1/nutrition/food/173944?grams=120" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "fdcId": 173944,
  "name": "Bananas, raw",
  "category": "Fruits and Fruit Juices",
  "per100g": {
    "energy_kcal": {
      "amount": 89,
      "unit": "kcal"
    },
    "protein": {
      "amount": 1.09,
      "unit": "g"
    },
    "fat": {
      "amount": 0.33,
      "unit": "g"
    },
    "carbohydrates": {
      "amount": 22.8,
      "unit": "g"
    },
    "fiber": {
      "amount": 2.6,
      "unit": "g"
    },
    "sugars": {
      "amount": 12.2,
      "unit": "g"
    },
    "water": {
      "amount": 74.9,
      "unit": "g"
    },
    "saturated_fat": {
      "amount": 0.112,
      "unit": "g"
    },
    "monounsaturated_fat": {
      "amount": 0.032,
      "unit": "g"
    },
    "polyunsaturated_fat": {
      "amount": 0.073,
      "unit": "g"
    },
    "trans_fat": {
      "amount": 0,
      "unit": "g"
    },
    "cholesterol": {
      "amount": 0,
      "unit": "mg"
    },
    "sodium": {
      "amount": 1,
      "unit": "mg"
    },
    "potassium": {
      "amount": 358,
      "unit": "mg"
    },
    "calcium": {
      "amount": 5,
      "unit": "mg"
    },
    "iron": {
      "amount": 0.26,
      "unit": "mg"
    },
    "magnesium": {
      "amount": 27,
      "unit": "mg"
    },
    "phosphorus": {
      "amount": 22,
      "unit": "mg"
    },
    "zinc": {
      "amount": 0.15,
      "unit": "mg"
    },
    "copper": {
      "amount": 0.078,
      "unit": "mg"
    },
    "manganese": {
      "amount": 0.27,
      "unit": "mg"
    },
    "selenium": {
      "amount": 1,
      "unit": "µg"
    },
    "vitamin_a_rae": {
      "amount": 3,
      "unit": "µg"
    },
    "vitamin_c": {
      "amount": 8.7,
      "unit": "mg"
    },
    "vitamin_d": {
      "amount": 0,
      "unit": "µg"
    },
    "vitamin_e": {
      "amount": 0.1,
      "unit": "mg"
    },
    "vitamin_k": {
      "amount": 0.5,
      "unit": "µg"
    },
    "thiamin_b1": {
      "amount": 0.031,
      "unit": "mg"
    },
    "riboflavin_b2": {
      "amount": 0.073,
      "unit": "mg"
    },
    "niacin_b3": {
      "amount": 0.665,
      "unit": "mg"
    },
    "vitamin_b6": {
      "amount": 0.367,
      "unit": "mg"
    },
    "folate_dfe": {
      "amount": 20,
      "unit": "µg"
    },
    "vitamin_b12": {
      "amount": 0,
      "unit": "µg"
    },
    "choline": {
      "amount": 9.8,
      "unit": "mg"
    },
    "caffeine": {
      "amount": 0,
      "unit": "mg"
    },
    "alcohol": {
      "amount": 0,
      "unit": "g"
    }
  },
  "portions": [
    {
      "description": "1 NLEA serving",
      "grams": 126
    },
    {
      "description": "1 extra large (9\" or longer)",
      "grams": 152
    },
    {
      "description": "1 large (8\" to 8-7/8\" long)",
      "grams": 136
    }
  ],
  "grams": 120,
  "forGrams": {
    "energy_kcal": {
      "amount": 106.8,
      "unit": "kcal"
    },
    "protein": {
      "amount": 1.308,
      "unit": "g"
    },
    "fat": {
      "amount": 0.396,
      "unit": "g"
    },
    "carbohydrates": {
      "amount": 27.36,
      "unit": "g"
    },
    "fiber": {
      "amount": 3.12,
      "unit": "g"
    },
    "sugars": {
      "amount": 14.64,
      "unit": "g"
    },
    "water": {
      "amount": 89.88,
      "unit": "g"
    },
    "saturated_fat": {
      "amount": 0.134,
      "unit": "g"
    },
    "monounsaturated_fat": {
      "amount": 0.038,
      "unit": "g"
    },
    "polyunsaturated_fat": {
      "amount": 0.088,
      "unit": "g"
    },
    "trans_fat": {
      "amount": 0,
      "unit": "g"
    },
    "cholesterol": {
      "amount": 0,
      "unit": "mg"
    },
    "sodium": {
      "amount": 1.2,
      "unit": "mg"
    },
    "potassium": {
      "amount": 429.6,
      "unit": "mg"
    },
    "calcium": {
      "amount": 6,
      "unit": "mg"
    },
    "iron": {
      "amount": 0.312,
      "unit": "mg"
    },
    "magnesium": {
      "amount": 32.4,
      "unit": "mg"
    },
    "phosphorus": {
      "amount": 26.4,
      "unit": "mg"
    },
    "zinc": {
      "amount": 0.18,
      "unit": "mg"
    },
    "copper": {
      "amount": 0.094,
      "unit": "mg"
    },
    "manganese": {
      "amount": 0.324,
      "unit": "mg"
    },
    "selenium": {
      "amount": 1.2,
      "unit": "µg"
    },
    "vitamin_a_rae": {
      "amount": 3.6,
      "unit": "µg"
    },
    "vitamin_c": {
      "amount": 10.44,
      "unit": "mg"
    },
    "vitamin_d": {
      "amount": 0,
      "unit": "µg"
    },
    "vitamin_e": {
      "amount": 0.12,
      "unit": "mg"
    },
    "vitamin_k": {
      "amount": 0.6,
      "unit": "µg"
    },
    "thiamin_b1": {
      "amount": 0.037,
      "unit": "mg"
    },
    "riboflavin_b2": {
      "amount": 0.088,
      "unit": "mg"
    },
    "niacin_b3": {
      "amount": 0.798,
      "unit": "mg"
    },
    "vitamin_b6": {
      "amount": 0.44,
      "unit": "mg"
    },
    "folate_dfe": {
      "amount": 24,
      "unit": "µg"
    },
    "vitamin_b12": {
      "amount": 0,
      "unit": "µg"
    },
    "choline": {
      "amount": 11.76,
      "unit": "mg"
    },
    "caffeine": {
      "amount": 0,
      "unit": "mg"
    },
    "alcohol": {
      "amount": 0,
      "unit": "g"
    }
  },
  "source": "USDA FoodData Central, SR Legacy (public domain, CC0)"
}
```

#### 3. Calculate recipe or meal totals

Takes food:grams pairs separated by semicolons, matches each food and returns per item macros plus total nutrients for the whole recipe or meal.

**Method:** `GET`

**Endpoint:** `/v1/nutrition/calculate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `items` | query | food:grams pairs separated by ; (or POST JSON {"items":[{"query":"banana","grams":120}]}) | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/nutrition-facts/v1/nutrition/calculate?items=eggs%3A100%3Boats%3A50%3Bwhole%20milk%3A200" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "items": [
    {
      "query": "eggs",
      "fdcId": 171287,
      "matched": "Egg, whole, raw, fresh",
      "grams": 100,
      "energy_kcal": 143,
      "protein_g": 12.6,
      "fat_g": 9.51,
      "carbohydrates_g": 0.72
    },
    {
      "query": "oats",
      "fdcId": 173904,
      "matched": "Cereals, oats, regular and quick, not fortified, dry",
      "grams": 50,
      "energy_kcal": 189.5,
      "protein_g": 6.6,
      "fat_g": 3.26,
      "carbohydrates_g": 33.85
    },
    {
      "query": "whole milk",
      "fdcId": 171265,
      "matched": "Milk, whole, 3.25% milkfat, with added vitamin D",
      "grams": 200,
      "energy_kcal": 122,
      "protein_g": 6.3,
      "fat_g": 6.5,
      "carbohydrates_g": 9.6
    }
  ],
  "totals": {
    "energy_kcal": {
      "amount": 454.5,
      "unit": "kcal"
    },
    "protein": {
      "amount": 25.5,
      "unit": "g"
    },
    "fat": {
      "amount": 19.27,
      "unit": "g"
    },
    "carbohydrates": {
      "amount": 44.17,
      "unit": "g"
    },
    "fiber": {
      "amount": 5.05,
      "unit": "g"
    },
    "sugars": {
      "amount": 10.965,
      "unit": "g"
    },
    "water": {
      "amount": 257.8,
      "unit": "g"
    },
    "saturated_fat": {
      "amount": 7.405,
      "unit": "g"
    },
    "monounsaturated_fat": {
      "amount": 6.274,
      "unit": "g"
    },
    "polyunsaturated_fat": {
      "amount": 3.45,
      "unit": "g"
    },
    "trans_fat": {
      "amount": 0.038,
      "unit": "g"
    },
    "cholesterol": {
      "amount": 392,
      "unit": "mg"
    },
    "sodium": {
      "amount": 231,
      "unit": "mg"
    },
    "potassium": {
      "amount": 583,
      "unit": "mg"
    },
    "calcium": {
      "amount": 308,
      "unit": "mg"
    },
    "iron": {
      "amount": 3.935,
      "unit": "mg"
    },
    "magnesium": {
      "amount": 101,
      "unit": "mg"
    },
    "phosphorus": {
      "amount": 571,
      "unit": "mg"
    },
    "zinc": {
      "amount": 3.85,
      "unit": "mg"
    },
    "copper": {
      "amount": 0.318,
      "unit": "mg"
    },
    "manganese": {
      "amount": 1.851,
      "unit": "mg"
    },
    "selenium": {
      "amount": 52.55,
      "unit": "µg"
    },
    "vitamin_a_rae": {
      "amount": 252,
      "unit": "µg"
    },
    "vitamin_c": {
      "amount": 0,
      "unit": "mg"
    },
    "vitamin_d": {
      "amount": 4.6,
      "unit": "µg"
    },
    "vitamin_e": {
      "amount": 1.4,
      "unit": "mg"
    },
    "vitamin_k": {
      "amount": 1.9,
      "unit": "µg"
    },
    "thiamin_b1": {
      "amount": 0.362,
      "unit": "mg"
    },
    "riboflavin_b2": {
      "amount": 0.872,
      "unit": "mg"
    },
    "niacin_b3": {
      "amount": 0.813,
      "unit": "mg"
    },
    "vitamin_b6": {
      "amount": 0.292,
      "unit": "mg"
    },
    "folate_dfe": {
      "amount": 73,
      "unit": "µg"
    },
    "vitamin_b12": {
      "amount": 1.79,
      "unit": "µg"
    },
    "choline": {
      "amount": 342.8,
      "unit": "mg"
    },
    "caffeine": {
      "amount": 0,
      "unit": "mg"
    },
    "alcohol": {
      "amount": 0,
      "unit": "g"
    }
  },
  "source": "USDA FoodData Central, SR Legacy (public domain, CC0)"
}
```

#### 4. List food categories

Returns the 25 USDA food categories, which you can pass as the category filter on search.

**Method:** `GET`

**Endpoint:** `/v1/nutrition/categories`

**Parameters:** none.

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/nutrition-facts/v1/nutrition/categories" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "categories": [
    "American Indian/Alaska Native Foods",
    "Baby Foods",
    "Baked Products"
  ],
  "source": "USDA FoodData Central, SR Legacy (public domain, CC0)"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the result is in the response body. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. The body explains the problem. |
| 401 | Unauthorized | The `x-api-market-key` header is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The requested item or path does not exist. |
| 429 | Too Many Requests | You went over 10 requests per second or used up your plan quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Every plan allows 10 requests per second. The Pro plan includes 25,000 calls a month and the Ultra plan 150,000; when a monthly quota is used up, further calls return `429 Too Many Requests` until the next billing period. The pay-as-you-go plan has no quota and bills US$0.0005 per successful call. If you receive a `429`, back off before retrying and honour any `Retry-After` header.

## FAQ

**Where does the nutrition data come from?**

USDA FoodData Central, SR Legacy, which is public domain (CC0). It covers 7,793 generic foods, not branded products.

**How do I get nutrients for a serving instead of 100 g?**

Call the food details endpoint with grams, for example grams=120, and read forGrams. The portions list gives typical gram weights, such as 1 cup sliced banana at 150 g.

**How do I format the items for the recipe calculator?**

Pass food:grams pairs separated by semicolons, for example items=eggs:100;oats:50;whole milk:200. Each item in the response shows which food was matched.

**Why does search return fewer nutrients than food details?**

Search returns calories, protein, fat and carbohydrates per 100 g to keep results short. Use the fdcId with the food details endpoint for all 36 nutrients.

**Which language should search queries use?**

English food names. Search prefers the common form of a food, so "eggs" matches a whole raw egg and "milk" matches whole milk.

**How much does the Nutrition Facts API cost?**

There is no free plan. Pay as you go costs US$0.0005 per call with no monthly fee. Pro is US$4.99 per month for 25,000 calls and Ultra is US$14.99 per month for 150,000 calls. All plans allow 10 requests per second.

## 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.


Nutrition API with 7,793 USDA foods and 36 nutrients: calories, protein, fat, carbs, vitamins and minerals per 100 g or any amount, plus recipe totals.