REST API 文件

基底網址 https://carbon.taux.io。唯讀、不需認證、有流量限制，JSON 請求內容上限 64 KB。REST API 與 MCP 工具共用同一套查詢與計算邏輯。

方法	路徑	說明	參數
GET	`/api/v1/sources`	列出官方資料來源與狀態。	無
GET	`/api/v1/factors`	搜尋排放係數。	查詢參數：query、category、factor_type、year、unit、limit、offset
GET	`/api/v1/factors/:id`	取得單一係數的完整資訊。	選填查詢參數 ?version= 指定版本
GET	`/api/v1/factors/:id/versions`	列出係數的歷史版本，新的在前。	無
GET	`/api/v1/electricity`	查詢指定年度的電力排碳係數。	查詢參數：year（必填）、usage_type（選填：industry_inventory、residential_tariff、utility_average）
POST	`/api/v1/calculate`	計算單一活動的排放量。	JSON：factor_id、quantity、quantity_unit、year（選填）、optional_context（選填）、factor_version（選填）
POST	`/api/v1/calculate/batch`	批次計算多筆活動。	JSON：{ "items": [...] }，每筆同 /api/v1/calculate，最多 50 筆
GET	`/api/v1/status`	各來源的同步狀態。	無
GET	`/health`	服務健康檢查。	無

錯誤格式

失敗時回傳：

{ "ok": false, "error": { "code": "...", "message": "...", "details": { } } }

code 是機器可讀的錯誤代碼，message 是說明，details 視情況附上。查不到係數、單位不相容、年度不符或缺少必要資料時，都會回傳明確錯誤，不會猜測。

計算範例

2025 年產業盤查使用的電力排碳係數，辦公室用電 12,000 度：

curl -X POST https://carbon.taux.io/api/v1/calculate \
  -H "content-type: application/json" \
  -d '{"factor_id":"tw-electricity-2025-industry-inventory","quantity":12000,"quantity_unit":"kWh","year":2025}'

回應（節錄）：

{
  "ok": true,
  "factor": {
    "id": "tw-electricity-2025-industry-inventory",
    "value": "0.466",
    "reference_year": 2025
  },
  "emissions_kg": "5592",
  "emissions_t": "5.592"
}

12,000 度 × 0.466 公斤CO2e/度 = 5592 公斤CO2e。完整回應另有公式、係數版本、來源網址與使用限制。

注意事項

係數 ID 請從 /api/v1/factors 或 /api/v1/electricity 的結果取得，不要自行猜測。
指定 year 時，必須與係數的適用年度相符，不會自動以其他年度代替。
燃料燃燒係數需要在 optional_context.lower_heating_value 提供低位熱值。
結果僅供參考，不是認證、第三方查證或法令遵循的依據。