Database Documentation
The food database behind the API
CookTool is built on a purpose-built food database that combines the scientific rigour of government nutritional research with the breadth of commercial product data — all normalised into a single, queryable structure.
8,262
Canonical ingredients
~2M
Branded products
5,432
FNDDS survey dishes
24.2M+
Nutrient data points
6
National nutrition databases
100%
CO₂ footprint coverage
Three-tier data model
Most food databases flatten everything into one table. CookTool uses a three-tier hierarchy that mirrors how food actually works — from raw ingredients up to finished packaged products.
The scientific foundation. Each record represents a single, well-defined food ingredient sourced from the USDA Standard Reference and SR Legacy datasets. These are the building blocks everything else resolves to.
- ✓Full nutrient profile (energy, macros, vitamins, minerals, amino acids)
- ✓Density table for volume-to-weight conversion (g/ml, g/cup)
- ✓Pattern-matched allergen flags (gluten, dairy, nuts, shellfish, etc.)
- ✓Ingredient category classification
Real-world food combinations from the USDA Food and Nutrient Database for Dietary Studies (FNDDS). These are foods as people actually eat them — mixed dishes, restaurant meals, and prepared foods — each decomposed into their Tier 1 components with gram amounts.
- ✓Decomposed into canonical ingredient components via
/survey-foods/:id/components - ✓WWEIA category codes for dietary analysis alignment
- ✓Nutrient values independently calculated from components
The full USDA Branded Food Products Dataset — every product that manufacturers have submitted to the USDA. Lookup by product name, brand, or scan a barcode directly via GTIN/UPC.
- ✓GTIN/UPC barcode lookup (exact match via indexed column)
- ✓Brand owner, market country, serving size, and ingredients list
- ✓Data quality flag:
medium(has serving size) orlow(no serving data) - ✓Linked nutrient data where manufacturer-provided
Nutrient coverage
Nutrient data is stored in a normalised structure — a sharednutrients table defines what each nutrient is (name, unit, USDA ID), while per-ingredient amounts live in join tables. This means you can filter, aggregate, and compare across thousands of ingredients without denormalisation problems.
Macronutrients
Energy (kcal & kJ), protein, total fat, carbohydrates, dietary fibre, sugars, water, alcohol
Vitamins
A, B1, B2, B3, B5, B6, B7, B9, B12, C, D, E, K — including multiple forms (e.g. D2 vs D3, alpha vs gamma tocopherol)
Minerals & trace
Calcium, iron, magnesium, phosphorus, potassium, sodium, zinc, copper, manganese, selenium, fluoride, iodine, chromium
Amino acid profiles (all 20 standard amino acids), fatty acid breakdown (saturated, monounsaturated, polyunsaturated, trans, omega-3/6), cholesterol, phytosterols, and carotenoids are all present for ingredients where the USDA has measured them. Not every ingredient has every nutrient — the database stores only what has been measured, never imputed zeros.
Multi-country nutrient sources
CookTool cross-links six peer-reviewed national nutrition databases under one schema. The country-aware resolver API automatically selects the best verified national source for the requested country, falling back to USDA SR for any missing nutrient.
| Database | Country | Source foods | Priority |
|---|---|---|---|
| USDA SR + Foundation Foods | 🇺🇸 United States | 8,262 | Universal backbone |
| PHE McCance & Widdowson | 🇬🇧 United Kingdom | 2,886 | country=GB |
| BLS Bundeslebensmittelschl. | 🇩🇪 Germany | 7,140 | country=DE |
| CIQUAL (ANSES) | 🇫🇷 France | 3,484 | country=FR |
| LIVSMEDEL_SE (SLV) | 🇸🇪 Sweden | 2,575 | country=SE |
| Matvaretabellen (Helsedir.) | 🇳🇴 Norway | 2,121 | country=NO |
| FRIDA (DTU) | 🇩🇰 Denmark | 1,381 | country=DK |
GET /v1/ingredients/:id/nutrients?country=DE returns German BLS values for nutrients where a verified cross-link exists, with USDA fallback for anything not covered by the national database.CO₂ footprint data
Every canonical ingredient carries an ISO 14040 / GHG Protocol-compliant carbon footprint value. Coverage is 100% — no ingredient returns a missing CO₂ value.
| Source | Records | DQR | Boundary |
|---|---|---|---|
| Poore & Nemecek 2018 | 4,358 | 1–2 | Cradle-to-retail (global mean) |
| AGRIBALYSE 3.2 | 138 | 2–3 | Cradle-to-plate (France/EU) |
| Category-median | 4,121 | 4–5 | Cradle-to-retail (derived) |
Standard
ISO 14040 / 14044 LCA
Protocol
GHG Protocol Product Standard
Characterisation
IPCC AR5 GWP100
GET /v1/ingredients/:id/carbon?country=FR returns kg CO₂e per kg food at the stated functional unit, with source dataset, DQR score, and uncertainty range. Pass country= to prioritise AGRIBALYSE values for French/EU products where available.Prep & yield factors
Raw-weight nutrition is misleading — a chicken breast loses 25–30% of its weight when cooked. Yield factors convert raw gram amounts to edible cooked weight, and cooking-loss factors adjust nutrient values accordingly. CookTool stores both per ingredient and per cooking method.
| Method | What changes |
|---|---|
| boiling | Water-soluble vitamins leach; weight increases for dry goods, decreases for meat |
| frying | Fat absorption + moisture loss; energy density increases significantly |
| baking | Moisture loss primary effect; protein and fat values concentrate |
| steaming | Minimal nutrient loss; closest to raw nutrient values |
| grilling | Fat drips away; protein concentrates; B vitamins reduce moderately |
GET /v1/ingredients/:id/yield?method=boiling returns the yield factor (e.g. 0.74) and nutrient retention factors for that ingredient × method combination. Multiply raw nutrient values by the retention factor to get cooked values.Unit conversion engine
Recipes specify ingredients in many different units depending on locale and convention. The unit conversion endpoint converts between weight, volume, and piece units using ingredient-specific density and piece-weight data.
Weight units
g, kg, mg, oz, lb
Volume units
ml, l, cup, tbsp, tsp, fl oz, pint
Piece units
piece, slice, clove, head, bunch (ingredient-specific)
Locale sets
US, UK, metric, AU, CA, and custom overrides
GET /v1/ingredients/:id/convert?from=cup&to=g&amount=2 returns the equivalent gram weight using the ingredient's specific density. Works for volume → weight, weight → volume, and piece → weight conversions.Canonical cross-linking
Every source food record from all six national databases is linked to a canonical USDA ingredient via verified canonical_ingredient_links. This means a query for “butter” can return matched records from PHE, BLS, CIQUAL, and USDA — all under a single canonical identifier.
Example: ingredient_id = 1001 (Butter, salted)
Minor differences in measured energy values between databases reflect genuine measurement differences between countries — the cross-linking preserves them rather than averaging, so your app can surface the most locally-relevant figure.
Allergen detection
Allergens are derived by running each ingredient name through a curated set of pattern-matching rules aligned with the EU 14 major allergens and the US FDA top-9. The result is stored in a separateingredient_allergens table (many-to-one per ingredient) so you can filter by allergen without touching the ingredient table itself.
Gluten
Dairy
Eggs
Nuts
Soy
Shellfish
Fish
Sesame
Filter by allergen via the allergen= query parameter on /v1/ingredients. Example: ?allergen=gluten returns only ingredients that contain gluten — useful for building allergy-safe recipe filters without client-side post-processing.
Density & volume conversion
Recipes use volume measures (cups, tablespoons, millilitres). Nutrition is always calculated by weight (grams). Theingredient_density table bridges this gap with measured density values for each ingredient.
| Column | Description |
|---|---|
| g_per_ml | Grams per millilitre — convert any liquid volume to weight |
| g_per_cup | Grams per US cup — pre-calculated convenience value |
| source | Where the density was measured (usda, literature, measured) |
Density data is present for 8,262 canonical ingredients. For solids the value represents the packed/typical density of the ingredient in its most common preparation state.
Branded products in depth
With over two million records, the branded tier is the largest in the database. Every product carries a rich metadata envelope beyond just name and nutrients.
| Field | What it enables |
|---|---|
| gtin_upc | Exact barcode lookup — scan a product, get its full nutritional profile instantly |
| brand / brand_owner | Filter by brand family; identify private-label vs. national brand products |
| market_country | Know which market a product was sold in (US, CA, GB, etc.) |
| serving_size + unit | Calculate per-serving nutrition without your own parsing logic |
| ingredients_list | Full free-text ingredients declaration as printed on pack |
| branded_food_category | Manufacturer-supplied category (e.g. "Breakfast Cereals", "Cheese") |
| data_quality flag | "medium" = serving size present; "low" = incomplete manufacturer data |
The gtin_upc column carries a dedicated database index, making barcode lookups sub-millisecond even across two million rows.
How it compares
There are several food databases available via API. Here is an honest comparison of what each does well and where they fall short.
- ✓Three-tier model — canonical, survey, and branded in one consistent schema
- ✓2M+ branded products with GTIN/UPC barcode index
- ✓25.2M nutrient data points — full amino acid and fatty acid profiles
- ✓Density table for volume-to-weight conversion built in
- ✓Survey foods decomposed into canonical ingredients (meal → raw components)
- ✓Allergen flags pre-computed, filterable via query parameter
- ✓Free tier available, no per-call billing surprises
- ✓Genuinely free and open source
- ✓Large branded product coverage globally
- ✗Crowd-sourced data with highly variable quality and completeness
- ✗No canonical ingredient layer — branded only
- ✗Nutrient data missing or inconsistent for a large portion of products
- ✗No density data, no allergen query filtering
- ✓The authoritative source — highest scientific quality
- ✓Free to download in full
- ✗Raw CSV dumps only — no REST API for production use
- ✗No unified schema across data types (SR Legacy, FNDDS, Branded use different structures)
- ✗No density data, no allergen flags, no barcode index
- ✗Significant ETL work required to make it queryable
- ✓Natural language food parsing (e.g. “two eggs and toast”)
- ✓Good restaurant menu coverage
- ✗Expensive at scale — per-call billing with no free self-serve tier
- ✗Nutrient depth limited to common macros and vitamins
- ✗No density data, no raw ingredient decomposition
- ✗Proprietary — no data portability
- ✓Recipe analysis and meal planning features built in
- ✓Diet and health label classification
- ✗Free tier is heavily rate-limited and requires attribution
- ✗Black-box data sourcing — no transparency on where values come from
- ✗No branded product barcode lookup on lower tiers
- ✗No amino acid or fatty acid detail at free tier