# USDA Food Nutrition Scraper - Calories, Macros & Nutrients (`ninhothedev/usda-food-scraper`) Actor

$0.5/1K 🔥 USDA food nutrition scraper! Calories, macros & 100+ nutrients for any food. No signup. JSON, CSV, Excel or API in seconds. Power nutrition apps & diet trackers ⚡

- **URL**: https://apify.com/ninhothedev/usda-food-scraper.md
- **Developed by:** [ninhothedev](https://apify.com/ninhothedev) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## USDA Food Nutrition Scraper — Calories, Macros & 100+ Nutrients

Get **official USDA nutrition data** for any food — calories, protein, carbs, fat, fiber, sugars, sodium, vitamins and minerals — straight from the U.S. Department of Agriculture's **FoodData Central** database (600,000+ foods, including branded supermarket products).

Search by keyword (`banana`, `greek yogurt`, `Cheerios`) or pull full nutrient records by FDC ID. **No signup needed** — the actor ships with the shared USDA `DEMO_KEY` and works out of the box. Add your own free key for higher limits.

***

### What you get

One dataset item per food, ready for a nutrition app, a diet tracker or a training set:

| Field | Description |
|---|---|
| `fdc_id` | FoodData Central ID (stable identifier) |
| `description` | Food name, e.g. `Bananas, raw` |
| `data_type` | `Foundation`, `SR Legacy`, `Survey (FNDDS)` or `Branded` |
| `food_category` | e.g. `Fruits and Fruit Juices` |
| `brand_owner` / `brand_name` | Manufacturer and brand (branded foods) |
| `ingredients` | Full ingredient statement (capped at 2,000 chars) |
| `serving_size` / `serving_size_unit` | e.g. `32` / `g` |
| `publication_date` | ISO date (`2019-04-01`) |
| `calories_kcal` | Energy in kcal (never kJ) |
| `protein_g`, `fat_g`, `carbs_g` | Core macros per 100 g |
| `fiber_g`, `sugars_g`, `saturated_fat_g`, `cholesterol_mg` | Extended macros |
| `sodium_mg`, `calcium_mg`, `iron_mg`, `potassium_mg`, `vitamin_c_mg` | Key micronutrients |
| `nutrient_count` | How many nutrients the record carries (up to 114) |
| `all_nutrients` | Compact `{name, value, unit}` list (first 40) |
| `url` | Link to the food on fdc.nal.usda.gov |
| `source`, `scraped_at` | `usda-fdc` + UTC timestamp |

Every field is nullable — USDA records vary a lot between branded and lab-analysed foods, so missing nutrients come back as `null` instead of silently becoming `0`.

#### Sample output

```json
{
  "fdc_id": 173944,
  "description": "Bananas, raw",
  "data_type": "SR Legacy",
  "food_category": "Fruits and Fruit Juices",
  "serving_size": null,
  "publication_date": "2019-04-01",
  "calories_kcal": 89.0,
  "protein_g": 1.09,
  "fat_g": 0.33,
  "carbs_g": 22.84,
  "fiber_g": 2.6,
  "sugars_g": 12.23,
  "sodium_mg": 1.0,
  "potassium_mg": 358.0,
  "vitamin_c_mg": 8.7,
  "nutrient_count": 114,
  "url": "https://fdc.nal.usda.gov/food-details/173944/nutrients",
  "source": "usda-fdc"
}
```

***

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | select | `search` | `search` = find foods by keyword, `foods` = fetch details by FDC ID |
| `queries` | array | `["banana", "chicken breast"]` | Search terms (search mode) |
| `fdcIds` | array | `[]` | FoodData Central IDs (foods mode) |
| `apiKey` | string | `DEMO_KEY` | Optional personal USDA API key |
| `maxItems` | integer | `100` | Hard cap on dataset items (max 1,000) |

```json
{
  "mode": "search",
  "queries": ["banana", "greek yogurt", "chicken breast"],
  "maxItems": 150,
  "apiKey": "DEMO_KEY"
}
```

Fetching specific foods:

```json
{
  "mode": "foods",
  "fdcIds": ["173944", "171077", "2012128"],
  "apiKey": "DEMO_KEY"
}
```

***

### About the DEMO\_KEY (and how to get a free key)

The USDA FoodData Central API is free, but every request needs an API key. It accepts the shared **`DEMO_KEY`**, which is why this actor runs with zero setup.

**Verified limits (measured against the live API):** with `DEMO_KEY` the API returns `X-RateLimit-Limit: 10` — roughly **10 requests per hour per IP address**, with a daily ceiling on top. That is enough for a few hundred foods per run (search returns 50 foods per request, detail lookups return 20 foods per request), but it is shared with everyone else using the demo key, so it can be exhausted.

**Get your own free key in 30 seconds** — no credit card, no approval wait:

1. Go to <https://fdc.nal.usda.gov/api-key-signup>
2. Enter your name and email.
3. The key arrives instantly by email.
4. Paste it into the **USDA API key** input field.

A personal key raises the limit to **1,000 requests/hour**, i.e. up to 50,000 foods per hour.

If the demo key is exhausted, the run fails with a clear message telling you to add your own key or retry in an hour — it never returns a half-empty dataset silently.

***

### Use cases

- **Nutrition apps** — back a calorie counter or macro tracker with authoritative government data instead of crowd-sourced entries.
- **Recipe analysis** — resolve every recipe ingredient to calories and macros to compute per-serving nutrition automatically.
- **Diet tracking & coaching** — build meal plans, check micronutrient coverage, generate client-facing nutrient reports.
- **Food datasets & research** — assemble branded-product datasets with ingredient statements for ML, market research or labelling compliance work.

***

### Pricing

Pay only for Apify platform usage — roughly **$0.5 per 1,000 foods**. Runs on 512 MB, no proxies required (the USDA API is public), and the actor batches requests to keep API and compute cost minimal.

***

### How it works

1. **Search mode** calls `/fdc/v1/foods/search` with 50 results per page and walks pages until `maxItems` is reached.
2. **Foods mode** calls the bulk `/fdc/v1/foods` endpoint in batches of 20 IDs (the USDA maximum), falling back to single `/fdc/v1/food/{id}` requests if the bulk call fails.
3. Nutrients are resolved by USDA `nutrientId` first, then `nutrientNumber`, then by name — so both the flat search shape and the nested detail shape map into one consistent schema.
4. Duplicate FDC IDs across queries are deduplicated automatically.

Requests use `curl_cffi` with a Chrome 124 TLS fingerprint and fall back to plain `urllib` if that is unavailable.

***

### Related actors

- [Fruityvice Scraper](https://apify.com/ninhothedev/fruityvice-scraper) — fruit nutrition and taxonomy
- [Open Food Facts Scraper](https://apify.com/ninhothedev/open-food-facts-scraper) — global branded product database
- [TheMealDB Scraper](https://apify.com/ninhothedev/themealdb-scraper) — recipes, ingredients and meal categories
- [Recipe Scraper](https://apify.com/ninhothedev/recipe-scraper) — structured recipes from recipe sites

***

### Legal & data source

Data comes from the U.S. Department of Agriculture's FoodData Central, a public-domain U.S. government dataset. USDA does not endorse any product or service. This actor only reads the official public API and stores no personal data.

# Actor input Schema

## `mode` (type: `string`):

How to collect foods. "search" runs keyword searches against the USDA FoodData Central database (best for discovery). "foods" fetches the full nutrient detail record for specific FDC IDs you already know.

## `queries` (type: `array`):

Food search terms, one per line - for example "banana", "greek yogurt", "chicken breast" or a brand name like "Cheerios". Used only in "search" mode. Each query is paged through until maxItems is reached.

## `fdcIds` (type: `array`):

FoodData Central IDs to fetch full nutrient details for, e.g. "173944" (Bananas, raw). Used only in "foods" mode. IDs are requested in batches of 20, the maximum the USDA API allows.

## `apiKey` (type: `string`):

Your personal USDA FoodData Central API key. Leave the default "DEMO\_KEY" to use the shared demo key - it works without any signup but is rate limited (~10 requests/hour per IP). A free personal key (1,000 requests/hour) takes 30 seconds to get at https://fdc.nal.usda.gov/api-key-signup

## `maxItems` (type: `integer`):

Maximum number of food items to push to the dataset across all queries or IDs. Keep it low when using the shared DEMO\_KEY, because every 50 foods costs one API request.

## Actor input object example

```json
{
  "mode": "search",
  "queries": [
    "banana",
    "chicken breast"
  ],
  "fdcIds": [],
  "apiKey": "DEMO_KEY",
  "maxItems": 100
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        "banana",
        "chicken breast"
    ],
    "fdcIds": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("ninhothedev/usda-food-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "queries": [
        "banana",
        "chicken breast",
    ],
    "fdcIds": [],
}

# Run the Actor and wait for it to finish
run = client.actor("ninhothedev/usda-food-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    "banana",
    "chicken breast"
  ],
  "fdcIds": []
}' |
apify call ninhothedev/usda-food-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=ninhothedev/usda-food-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/AOOZrSs4FqOicfw4P/builds/pwHl1MbO691hekiSM/openapi.json