栄養素ティア & ADT

成分 API は栄養素をティアで分け、各栄養値は種別（kind）を保持したまま返します。「微量（Tr）」や「未測定」を 0 に潰さないのが、このデータの中核的な価値です。

ティア（core / extended）

ティア	含まれる栄養素	取得方法
core（既定）	エネルギー(kcal)・たんぱく質・脂質・炭水化物・食塩相当量＋食物繊維総量	既定で返る
extended	カルシウム・鉄・カリウム・ビタミン A・D・B1・B2・C	`?include=extended`

一般的な栄養成分表に載る範囲が core、ビタミン・ミネラル類が extended です。 core は食事管理アプリの土台として最も使う範囲なので、既定で返します。

# 既定（core のみ）
curl "https://api.example.com/v1/foods/01001" -H "X-API-Key: fnk_xxxx"
 
# extended を追加（ビタミン・ミネラル）
curl "https://api.example.com/v1/foods/01001?include=extended" -H "X-API-Key: fnk_xxxx"

fields で絞り込む

必要な栄養素だけが欲しいときは fields= でキーを指定します。

curl "https://api.example.com/v1/foods/01001?fields=energy_kcal,protein" \
  -H "X-API-Key: fnk_xxxx"

栄養値の kind（型保存契約）

各栄養値は { kind, value?, unit, note? } の形を取ります。kind は成分表の元表記を **判別共用体（ADT）**として保持したもので、次の 6 種類です。

kind	元表記	意味	`value`
`measured`	`N`	測定値	あり
`estimated`	`(N)`	推定値	あり
`trace`	`Tr`	微量（定量下限未満）	なし
`estimatedTrace`	`(Tr)`	推定の微量	なし
`notMeasured`	`-` / 空欄	未測定	なし
`measuredWithNote`	`N†`	測定値（注記付き）	あり（＋ `note`）

value が無い種別（trace・estimatedTrace・notMeasured）を 0 として扱うと、「微量に含まれる」と「測定していない」と「含まれない」が区別できなくなります。 API はこの区別を保ったまま返すので、表示や計算の方針はクライアント側で選べます。

{
  "nutrients": {
    "energy_kcal":  { "kind": "measured",  "value": 343,  "unit": "kcal" },
    "protein":      { "kind": "estimated", "value": 11.3, "unit": "g" },
    "fat":          { "kind": "measured",  "value": 6.0,  "unit": "g" },
    "carbohydrate": { "kind": "measured",  "value": 64.9, "unit": "g" },
    "salt":         { "kind": "measured",  "value": 0.0,  "unit": "g" },
    "dietaryFiber": { "kind": "trace",     "unit": "g" }
  }
}

unit は栄養素カタログから合成され、すべての種別に付きます。任意量へのスケーリングでは measured / estimated のみ線形にスケールし、trace / estimatedTrace / notMeasured は素通しされます（ポーションを参照）。

栄養素カタログ（名称・単位・分類・ティア）は GET /v1/nutrients?tier=core|extended|all で取得できます。