# USDA FoodData Central — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search across thousands of foods to get detailed nutritional information, serving sizes, and ingredient data from USDA's comprehensive food database. Find nutrition facts for branded products, legacy foods, and foundation foods all in one place.

**Category:** Food & Dining | **Website:** [fdc.nal.usda.gov/](https://fdc.nal.usda.gov/) | **Docs:** [parse.bot/marketplace/aef5bce9-346b-40c5-88a2-12151ae1a696/fdc-nal-usda-gov-api](https://parse.bot/marketplace/aef5bce9-346b-40c5-88a2-12151ae1a696/fdc-nal-usda-gov-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-fdc-nal-usda-gov-api-aef5bce9/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_food_details

Retrieve the full nutritional record for a single food item by its FDC ID. Returns comprehensive data including all nutrients with analysis details, food measures, attributes, input foods, and source samples. The response shape varies by food type (Foundation includes nutrientAnalysisDetails; Branded includes labelNutrients).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fdc_id` | string | Yes | The FDC ID of the food item (e.g. '1750340') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fdc-nal-usda-gov-api-aef5bce9/get_food_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fdc_id":"<string>"}'
```

### get_food_nutrients

Retrieve structured nutritional values for a food item, categorized into macronutrients, vitamins, minerals, lipids, and other. Each category is a map of nutrient name to an object containing amount, unit, and name. Derived from the full food detail record by classifying each nutrient.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fdc_id` | string | Yes | The FDC ID of the food item (e.g. '1750340') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fdc-nal-usda-gov-api-aef5bce9/get_food_nutrients \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fdc_id":"<string>"}'
```

### get_food_serving_sizes

Extract serving size and measurement unit data for a food item. Returns serving size value, unit, household serving text, package weight, and food measures. Branded foods typically have servingSize and servingSizeUnit populated; Foundation foods rely on foodMeasures.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fdc_id` | string | Yes | The FDC ID of the food item (e.g. '454004') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fdc-nal-usda-gov-api-aef5bce9/get_food_serving_sizes \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fdc_id":"<string>"}'
```

### get_multiple_foods

Fetch full details for multiple food items in a single request by providing comma-separated FDC IDs. Each item in the response has the same shape as get_food_details. Items that fail to resolve are silently omitted from results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fdc_ids` | string | Yes | Comma-separated list of FDC IDs (e.g. '1750340,454004') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fdc-nal-usda-gov-api-aef5bce9/get_multiple_foods \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fdc_ids":"<string>"}'
```

### list_foods

Retrieve a paged list of all available foods sorted alphabetically by description. Optionally filter by data type. Uses an empty search query internally to enumerate the full database. Paginates via page number.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `data_types` | string | No | Comma-separated list of data types to include: Foundation, SR Legacy, Survey (FNDDS), Branded, Experimental. Omitting returns all types. |
| `page` | integer | No | Page number |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fdc-nal-usda-gov-api-aef5bce9/list_foods \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data_types":"<string>","page":"<integer>"}'
```

### search_foods

Full-text search over the FoodData Central database. Matches query against food descriptions and ingredients. Supports filtering by data type and brand owner, sorting by description/fdcId/publishedDate. Paginates via page number. Each result includes summary nutrient data; use get_food_details for the full record.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brand_owner` | string | No | Filter by exact brand owner name (e.g. 'TREECRISP 2 GO') |
| `data_types` | string | No | Comma-separated list of data types to include: Foundation, SR Legacy, Survey (FNDDS), Branded, Experimental. Omitting returns all types. |
| `page` | integer | No | Page number to retrieve |
| `query` | string | Yes | Search keyword (e.g. 'apple', 'chicken breast') |
| `sort_by` | string | No | Field to sort by |
| `sort_order` | string | No | Sort direction |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fdc-nal-usda-gov-api-aef5bce9/search_foods \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand_owner":"<string>","data_types":"<string>","page":"<integer>","query":"<string>","sort_by":"<string>","sort_order":"<string>"}'
```