API reference

Food

GET /v1/foods/{id}

Get, search, match, and similar foods.

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

GET /v1/foods/{id}

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

Search

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

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

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.

Food object

{
  "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.