# USDA FoodData Central Scraper (`crawlerbros/usda-food-data-scraper`) Actor Scrape USDA FoodData Central - search 600k+ foods, get full nutritional profiles (calories, protein, fat, carbs, vitamins, minerals). Search by keyword, lookup by FDC ID, or browse by data type. - **URL**: https://apify.com/crawlerbros/usda-food-data-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Developer tools, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 FoodData Central Scraper Extract nutritional data for 600,000+ foods from the **USDA FoodData Central** (FDC) database — the official U.S. government source for food composition data. Get calories, macros (protein, fat, carbs), fiber, sugar, sodium, cholesterol, vitamins, minerals, and more. ### What data do you get? Each record includes: | Field | Description | |---|---| | `fdcId` | USDA FDC unique ID | | `description` | Food name | | `dataType` | Foundation / SR Legacy / Branded / Survey (FNDDS) / Experimental | | `foodCategory` | Category (e.g. Fruits, Vegetables, Dairy) | | `brandName` | Brand name (Branded foods only) | | `ingredients` | Full ingredient list | | `servingSize` | Serving size in grams | | `servingSizeUnit` | Unit string (g, ml, oz, etc.) | | `calories` | Energy (kcal per 100g) | | `protein` | Protein (g per 100g) | | `fat` | Total fat (g per 100g) | | `carbohydrates` | Total carbohydrates (g per 100g) | | `fiber` | Dietary fiber (g per 100g) | | `sugar` | Total sugars (g per 100g) | | `sodium` | Sodium (mg per 100g) | | `cholesterol` | Cholesterol (mg per 100g) | | `potassium` | Potassium (mg per 100g) | | `calcium` | Calcium (mg per 100g) | | `iron` | Iron (mg per 100g) | | `vitaminC` | Vitamin C (mg per 100g) | | `vitaminA` | Vitamin A (IU per 100g) | | `nutrientCount` | Total number of nutrient entries in record | | `scrapedAt` | ISO 8601 timestamp of extraction | Fields with no available data are omitted from the record. ### Input parameters | Parameter | Type | Description | |---|---|---| | `mode` | Select | **searchFoods** (default): search by keyword · **getFoodDetails**: lookup by FDC ID · **listFoods**: browse by data type | | `query` | Text | Search keyword (required for `searchFoods` mode). E.g. `apple`, `chicken breast`, `whole wheat bread` | | `fdcIds` | String list | One or more FDC IDs for `getFoodDetails` mode (e.g. `171705`, `454004`) | | `dataType` | Select | Data type for `listFoods` mode: Foundation, SR Legacy, Branded, Survey (FNDDS), Experimental | | `apiKey` | Text | Your free USDA API key (optional). Get one free at [api.data.gov](https://api.data.gov). Without it, the DEMO_KEY is used (30 req/hour, 50 req/day) | | `maxItems` | Integer | Maximum number of records to return (1–200, default 25) | ### Usage examples #### Search for foods by keyword ```json { "mode": "searchFoods", "query": "avocado", "maxItems": 20 } ```` #### Look up specific foods by FDC ID ```json { "mode": "getFoodDetails", "fdcIds": ["171705", "2346009", "454004"], "maxItems": 10 } ``` #### Browse Foundation reference foods ```json { "mode": "listFoods", "dataType": "Foundation", "maxItems": 50 } ``` #### Use your own API key for higher limits Register for a free key at [api.data.gov/signup](https://api.data.gov/signup/) (no cost, immediate access) to get 1,000 requests/hour instead of the DEMO\_KEY limits. ```json { "mode": "searchFoods", "query": "salmon", "apiKey": "YOUR_API_KEY_HERE", "maxItems": 100 } ``` ### Data types explained | Data type | Description | |---|---| | **Foundation** | Carefully curated reference foods with extensive nutrient data. Best for research and nutrition analysis. | | **SR Legacy** | USDA Standard Reference database (~8,000 foods). The classic reference used by nutritionists for decades. | | **Branded** | Commercial branded foods from manufacturer labels (~400,000 products). | | **Survey (FNDDS)** | Foods as consumed in USDA dietary surveys. Includes mixed dishes and food-as-eaten data. | | **Experimental** | Research and experimental food data. | ### Use cases - **Nutrition analysis apps** — build meal planners, recipe calculators, or calorie trackers - **Food research** — compare nutrient profiles across food categories - **Diet compliance tools** — filter foods by macros or micronutrients - **Restaurant and recipe databases** — enrich menus with USDA-verified nutrition data - **Academic research** — access standardized nutritional data for studies - **Product development** — benchmark branded products against reference foods ### API rate limits The DEMO\_KEY (used by default) allows **30 requests/hour** and **50 requests/day**. This is sufficient for the default `maxItems=25` setting. For higher-volume use, register at [api.data.gov](https://api.data.gov/signup/) for a free personal key with **1,000 requests/hour** and **no daily cap**. ### FAQ **Q: Is a USDA API key required?** No. The DEMO\_KEY works out of the box for typical scraping tasks. Provide your own key only if you need more than 50 requests per day. **Q: What is an FDC ID?** The FDC ID (FoodData Central ID) is the unique identifier assigned to each food in the USDA database. You can find FDC IDs by searching at [fdc.nal.usda.gov](https://fdc.nal.usda.gov). **Q: Are all nutrient values per 100g?** Yes. All macros, vitamins, and mineral values are per 100 grams of the food as reported by the USDA, unless otherwise noted in the original record. **Q: Why are some nutrient fields missing from a record?** If the USDA database doesn't have a specific nutrient measurement for a food, that field is omitted from the output (rather than showing null). This ensures clean, reliable data. **Q: How current is the data?** The USDA FoodData Central database is continuously updated. The scraper fetches live data from the official USDA API at run time. **Q: How do I find FDC IDs?** Visit [fdc.nal.usda.gov](https://fdc.nal.usda.gov), search for any food, and copy the FDC ID from the URL or food detail page. # Actor input Schema ## `mode` (type: `string`): How to query the USDA FoodData Central API. ## `query` (type: `string`): Keyword to search for (mode=searchFoods). E.g. 'apple', 'chicken breast', 'whole wheat bread'. ## `fdcIds` (type: `array`): One or more FDC IDs to look up (e.g. 171705, 2346009). Used only in getFoodDetails mode. ## `dataType` (type: `string`): Type of food data to browse. Foundation: curated reference foods. SR Legacy: USDA Standard Reference. Branded: commercial branded foods. Survey (FNDDS): dietary study foods. Experimental: research data. ## `apiKey` (type: `string`): Your free USDA FoodData Central API key (register at api.data.gov for higher rate limits). Leave blank to use the DEMO\_KEY (30 req/hour, 50 req/day). ## `maxItems` (type: `integer`): Maximum number of food records to return. ## Actor input object example ```json { "mode": "searchFoods", "query": "apple", "fdcIds": [], "dataType": "Foundation", "maxItems": 25 } ``` # Actor output Schema ## `foods` (type: `string`): Dataset containing all scraped USDA food records with nutritional information. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "searchFoods", "query": "apple", "fdcIds": [], "dataType": "Foundation", "maxItems": 25 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/usda-food-data-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "searchFoods", "query": "apple", "fdcIds": [], "dataType": "Foundation", "maxItems": 25, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/usda-food-data-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 '{ "mode": "searchFoods", "query": "apple", "fdcIds": [], "dataType": "Foundation", "maxItems": 25 }' | apify call crawlerbros/usda-food-data-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/usda-food-data-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "USDA FoodData Central Scraper", "description": "Scrape USDA FoodData Central - search 600k+ foods, get full nutritional profiles (calories, protein, fat, carbs, vitamins, minerals). Search by keyword, lookup by FDC ID, or browse by data type.", "version": "1.0", "x-build-id": "ARR5RRIx4XYXn8Ldq" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~usda-food-data-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-usda-food-data-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~usda-food-data-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-usda-food-data-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~usda-food-data-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-usda-food-data-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "searchFoods", "getFoodDetails", "listFoods" ], "type": "string", "description": "How to query the USDA FoodData Central API.", "default": "searchFoods" }, "query": { "title": "Search query", "type": "string", "description": "Keyword to search for (mode=searchFoods). E.g. 'apple', 'chicken breast', 'whole wheat bread'.", "default": "apple" }, "fdcIds": { "title": "FDC IDs (mode=getFoodDetails)", "type": "array", "description": "One or more FDC IDs to look up (e.g. 171705, 2346009). Used only in getFoodDetails mode.", "default": [], "items": { "type": "string" } }, "dataType": { "title": "Data type (mode=listFoods)", "enum": [ "Foundation", "SR Legacy", "Branded", "Survey (FNDDS)", "Experimental" ], "type": "string", "description": "Type of food data to browse. Foundation: curated reference foods. SR Legacy: USDA Standard Reference. Branded: commercial branded foods. Survey (FNDDS): dietary study foods. Experimental: research data.", "default": "Foundation" }, "apiKey": { "title": "USDA API key (optional)", "type": "string", "description": "Your free USDA FoodData Central API key (register at api.data.gov for higher rate limits). Leave blank to use the DEMO_KEY (30 req/hour, 50 req/day)." }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 200, "type": "integer", "description": "Maximum number of food records to return.", "default": 25 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```