# Food

USDA FoodData Central rows (Branded, SR Legacy, FNDDS, Foundation) with Open Food Facts pack shots joined on GTIN.

MCP: `get_food`, `search_foods`, `resolve_food`, `similar_foods`

## Get a food

```http
GET /v1/foods/{id}
```

`id` is `fds_fo_…`. Merged ids 301 to the survivor.

## Search

```http
GET /v1/foods/search?q=cheddar&type=branded&has_image=true
```

| Query | Notes |
|---|---|
| `q` | Name prefix first, then trigram. Required unless `brand`, `type`, or `category` is set |
| `brand` | Brand display-name filter |
| `type` | `branded` · `sr_legacy` · `survey` · `foundation` |
| `category` | Exact category string |
| `has_image` | `true` / `false` |
| `limit` | Default 20, max 50 |

## Resolve a name

```http
POST /v1/match
{ "name": "Cheddar Cheese", "brand": "Tillamook" }
```

Same match route as books. A valid `gtin` short-circuits to one `exact_gtin` candidate. Read `candidates[0]`. `POST /v1/foods/match` is an alias.

## Similar foods

```http
GET /v1/foods/{id}/similar
GET /v1/gtin/{gtin}/similar
```

Same category, closest label macros (kcal, protein, fat, carbs, sugars, sodium). Precomputed. Not collaborative filtering.

## Popular

```http
GET /v1/foods/popular?limit=24
```

Shelf ranking: Foundation > SR Legacy > FNDDS > Branded, plus image, GDSN, and recency.

## Food object

```json
{
  "id": "fds_fo_…",
  "schema_version": "food.v1",
  "data_type": "branded",
  "name": "MEDIUM CHEDDAR NATURAL CHEESE",
  "brand": { "id": "fds_fb_…", "name": "Tillamook", "owner": "…" },
  "gtin14": "00072830007115",
  "gtin": "072830007115",
  "fdc_id": 2345678,
  "category": "Cheese",
  "ingredients": "…",
  "serving": { "size": 28, "unit": "g", "household": "1 oz" },
  "nutrients": [{ "id": 1008, "nbr": "208", "name": "Energy", "unit": "KCAL", "amount": 403, "per": "100g" }],
  "label": { "kcal": 403, "protein_g": 23, "fat_g": 33, "sodium_mg": 621 },
  "images": [{
    "role": "front",
    "url": "/media/foods/fds_fo_…/front.400.jpg",
    "license": "CC-BY-SA-3.0",
    "source": "openfoodfacts",
    "attribution_url": "https://world.openfoodfacts.org/product/072830007115"
  }],
  "provenance": { "source": "usda_fdc", "license": "CC0", "fdc_release": "2026-04" },
  "release": "2026-10.1"
}
```

Nutrients are **per 100 g**. Branded values are label-derived. `quality_flags` marks implausible numbers (for example sodium > 100,000 mg/100 g).

## Images

Served from `GET /media/foods/{id}/{front|nutrition|ingredients}.400.jpg` (no auth). Copied from the Open Food Facts AWS image dump. Product images are **CC BY-SA**. Attribute Open Food Facts and link `attribution_url` wherever an image appears.

A photo license is not a brand blessing. Do not imply a partnership. Do not train generative models on pack shots.

## Sources

| Data | Source | License |
|---|---|---|
| Nutrition, ingredients, categories | USDA FoodData Central (April 2026) | CC0 / public domain |
| Pack shots | Open Food Facts images only | CC BY-SA 3.0 |

The Open Food Facts **product database** is not stored in Neon (ODbL). The pipeline may read it transiently to pick which image is the front / nutrition / ingredients shot.