Nutrition API

One request, five groups, per 100 g

GET /v1/foods/{id}/nutrients takes the food's UUID in the path and nothing else: no query parameters, no body, no lang. The id is the same one every other endpoint returns, so a hit from the Food Search API or the Barcode Lookup API becomes a full breakdown with one more call. Ids are deterministic across re-imports, so you can store them and keep calling this URL.

The response is a flat object with food_id plus five fixed groups: macros, fats, minerals, vitamins and other. Every key is always present and every value is either a number or null. Counting the keys in the current schema gives 41 nutrient fields, which is where the 40+ figure comes from. Units are in the key name (energy_kcal, sodium_mg, selenium_mcg, vitamin_a_iu), so you never carry a separate unit table.

All values are per 100 g of the product as sold. To show a serving, multiply by grams divided by 100. The food record's serving_size_raw is label text (for the sample Coca-Cola record it is "1 can (330 ml)"), so the conversion from that text to grams is yours to make.

• macros (10 keys) covers energy in kcal and kJ, protein, carbs, fat, sugars, fiber, alcohol, starch and polyols; fats (7) adds saturated, trans, mono- and polyunsaturated, omega3, omega6 and cholesterol_mg
• minerals (12) runs from sodium_mg and salt_g to selenium_mcg and iodine_mcg; vitamins (11) reports A and D in IU, B9 and B12 in mcg, the rest in mg; other holds added_sugars_g

Reading nulls and zeros correctly

The sample response for food 62ea12b8-b260-c288-5c38-3a4906f5d6dd shows the typical Open Food Facts pattern: energy_kcal 42, energy_kj 180.2, carbs_g 10.6, sugars_g 10.6, added_sugars_g 5.3, explicit zeros for proteins_g, fat_g, saturated_fat_g, sodium_mg and salt_g, and null for everything else, from fiber_g to the whole vitamins group.

Treat the two states differently. A 0 is a value the source reported; a null means the nutrient is not on the label or not in the source. Never coerce null to 0 before summing a day's intake, or a meal built from partially labeled products will silently under-report vitamins and minerals. Show a dash or "not reported" instead.

Coverage follows provenance. Rows with source usda_foundation or usda_sr_legacy are USDA laboratory analyses and populate the vitamin and mineral groups, so most keys are numbers. Rows with source usda (USDA Branded Foods) and rows from Open Food Facts are transcribed from packaging, so they are reliable for the mandatory label nutrients and often null beyond them. The source field on the food record tells you which case you are in before you render the table.

• Render null as unknown, not as zero; only aggregate keys that are non-null across every item in the meal.
• sodium_mg and salt_g both exist because labels differ by region; use whichever your audience expects and fall back to the other.

When you actually need this call

Every food record from the Food Database API and every barcode match already includes nutrition_summary with six headline values: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g and fiber_g. Search hits are lighter rows without it. For a scanner result, a detail card or a quick calorie log, that object is usually enough and costs no nutrient breakdown.

Reserve /nutrients for the detail screen or the moment a user asks about sodium, saturated fat, cholesterol or a specific vitamin. Search or scan, show the summary, fetch the breakdown on tap. On the Free plan this is also what keeps you inside the 25-per-day allowance while you build.

The captured response headers carry no Cache-Control, so caching is your job. Ids are stable and values only change when a product is re-imported, so a cache keyed on food_id and held for hours or days is safe.

The Free-plan allowance, header by header

On the Free plan each successful breakdown draws down a separate daily counter of 25, reported on every response as X-RateLimit-Nutrients-Limit, X-RateLimit-Nutrients-Remaining and X-RateLimit-Nutrients-Reset. Read Remaining before a burst of detail fetches and you can fall back to nutrition_summary instead of hitting the wall mid-session.

At zero the endpoint returns 429 with error "Nutrients daily allowance exceeded", an upgrade_url in the body, and Retry-After holding the seconds until midnight UTC. A rejected call consumes neither a breakdown nor a daily request, and does not move the reset. Paid plans have no such counter; their nutrient calls are bounded only by the plan's daily request quota (shared across all keys on the account) and the per-key per-second limit.

If you are on Starter or above and working through a large catalog, fetch the base records through the Bulk Food Lookup API first and call /nutrients only for the ids whose summary is not enough.