API 文件

45 個計算模型與分析工具端點，依三層架構分類

第一層自然資產帳戶層 → 第二層生態系服務流量層 → 第三層財務╱市場層

快速導航

第一層帳戶層帳戶層模組說明

第二層服務流量層生物多樣性 (14) 環境系統 (10) 生態系統 (12) 整合評估框架

第三層財務市場層自然碳匯 MRV (8) 自然資本估值 (1)

API 基本資訊

計算模型 Base URL:	`http://23.239.8.18:5003/api/calculations`
工具端點 Base URL:	`http://23.239.8.18:5003/indicators/` 及各 Blueprint 前綴
Authentication:	Required（Session-based login）
Content-Type:	`application/json`
Method:	`POST` 計算端點／ `GET` 查詢端點

Success Response:

{
  "success": true,
  "result": { /* 模型輸出 */ }
}

Error Response:

{
  "success": false,
  "error": "Error message"
}

第一層：自然資產帳戶層

帳戶層模組（SEEA 帳戶框架、GIS 空間分析、自然活動記帳、計算稽核日誌）為資料記錄與追蹤工具，資料透過各自的頁面介面輸入，不提供獨立計算 API 端點。

SEEA 帳戶框架 /seea/

GIS 空間分析 /gis/

自然活動記帳 /activity/

計算稽核日誌 /audit/log

第二層：生態系服務流量層 36 個端點

生物多樣性 API（14 個）

核心指標計算 /api/calculations/biodiversity/...

1. Shannon 指數計算

POST /biodiversity/shannon

計算物種多樣性 Shannon-Wiener 指數 (H' = -Σ pᵢ × ln pᵢ)

Request:

{
  "species": [
    {"name": "物種A", "count": 50},
    {"name": "物種B", "count": 30}
  ]
}

Response:

{
  "shannon_index": 0.673,
  "total_individuals": 80,
  "species_count": 2
}

2. Simpson 指數計算

POST /biodiversity/simpson

計算物種多樣性 Simpson 指數 (D = 1 − Σ pᵢ²)

3. 物種-面積關係（SAR）

POST /biodiversity/sar

預測不同面積的物種數量變化與經濟價值 (S = c × Aᶻ)

Request:

{
  "area_before": 1.0,
  "area_after": 1.5,
  "unit_cost": 30000
}

Response:

{
  "species_before": 10.0,
  "species_after": 11.07,
  "species_change": 1.07,
  "economic_value": 32100
}

4. 指數增長模型

POST /biodiversity/growth/exponential

預測族群指數增長 (N(t) = N₀ × e^(rt))

5. 邏輯斯蒂增長模型

POST /biodiversity/growth/logistic

考慮環境容量限制的族群增長預測

6. MSA 損失評估

POST /biodiversity/msa

評估平均物種豐度（Mean Species Abundance）損失與經濟影響

Shannon 三段式貨幣化路徑（Method A / B / C）/api/calculations/biodiversity/shannon-to-value/...

7. Method A — 生態系服務法（BEF 路徑）

POST /biodiversity/shannon-to-value/method-a

Shannon H' → 生態功能 → 服務流量 → 貨幣值，使用台灣各生態系分區 BEF 參數

Request:

{
  "shannon_index": 2.5,
  "area_ha": 50,
  "ecosystem_type": "forest",
  "region": "central",
  "discount_rate": 0.03,
  "time_horizon": 30
}

Response:

{
  "method": "Method A",
  "annual_value_ntd": 3250000,
  "npv_ntd": 61540000,
  "value_per_ha_ntd": 65000,
  "confidence_tier": "Tier 1",
  "reference": "林務局 2021"
}

8. Method B — 效益轉移法

POST /biodiversity/shannon-to-value/method-b

以台灣參考場址效益轉移，匹配相近生態類型並調整所得與物價。Request Body：同 Method A

9. Method C — WTP 保育意願法

POST /biodiversity/shannon-to-value/method-c

以社會支付意願（Stated Preference）評估生物多樣性保育價值

額外欄位：

{
  ...同 Method A...
  "species_count": 45,
  "affected_population": 1000000,
  "has_charismatic_species": false
}

10. 三方法比較分析

POST /biodiversity/shannon-to-value/all-methods

一次執行 Method A/B/C，回傳三方法對比、Low/Base/High 信賴區間與建議。Request Body：同 Method C

11. 貨幣化估值報告

POST /biodiversity/shannon-to-value/report

生成格式化文字報告，含方法論說明、信賴區間、參數來源，可直接輸出或下載。Request Body：同 Method C

生物多樣性工具端點 /indicators/biodiversity-analysis/...

12. BEF 有效組合查詢

GET /indicators/biodiversity-analysis/bef-valid-combos

回傳生態系類型 × 服務類型所有有效 BEF 參數組合（動態下拉選單用）

13. BEF 三段式功能-服務-價值路徑

POST /indicators/biodiversity-analysis/three-stage

生物多樣性指標 → 生態功能改變 → 服務流量改變 → 貨幣價值（完整三段路徑）

Request:

{
  "ecosystem_type": "wetland",
  "service_type": "water_purification",
  "area_ha": 30.5,
  "shannon_before": 1.8,
  "shannon_after": 2.5,
  "discount_rate": 0.03,
  "time_horizon": 30
}

Response:

{
  "stage1_function_change": 0.42,
  "stage2_service_change_m3": 126000,
  "stage3_annual_value_ntd": 882000,
  "npv_ntd": 18540000,
  "confidence_tier": "Tier 1"
}

14. UK BNG 棲地淨增益計算

POST /indicators/bng-analysis/calculate

依 UK Statutory Biodiversity Metric（June 2026）計算開發前後棲地單位，輸出淨增益 %

Request:

{
  "habitats": [
    {
      "name": "Coastal wetland",
      "area_ha": 5.0,
      "condition": 2.5,    // 1.0/1.5/2.0/2.5/3.0
      "spatial_risk": 1.0, // Within=1.0/Neighbouring=0.75/Outside=0.50
      "phase": "before"
    }
  ]
}

Response:

{
  "units_before": 12.5,
  "units_after": 15.8,
  "net_gain_pct": 26.4,
  "trading_rule_ok": true,
  "irreplaceable_warning": false
}

環境系統 API（10 個）

空氣品質 /api/calculations/air-quality/...

1. 高斯煙羽擴散模型

POST /air-quality/gaussian

模擬大氣污染物擴散濃度分布（PG 穩定度 A–F，Briggs σ 公式，地面完全反射）

Request:

{
  "Q": 100,       // 排放率 (g/s)
  "u": 3.0,       // 風速 (m/s)
  "x": 1000,      // 下風距離 (m)
  "y": 0,         // 橫風距離 (m)
  "H": 50,        // 有效高度 (m)
  "sigma_y": 100,
  "sigma_z": 50
}

Response:

{
  "concentration": 0.0012,
  "unit": "g/m³",
  "economic_impact": 5000
}

2. AQI 計算器

POST /air-quality/aqi

依台灣 EPA 標準線性內插計算空氣品質指數（7種污染物子指標）

3. 統計預測模型

POST /air-quality/prediction

基於氣象因子預測空氣品質趨勢

4. 健康成本估算

POST /air-quality/health-cost

濃度-反應函數 × VSL（PM2.5 優先、無則 PM10；僅含死亡）。需提供 pm25 或 pm10（μg/m³）、population；選填 crf_source、counterfactual、vsl、baseline_mortality_rate

地下水與土壤 /api/calculations/groundwater/...

5. 溶質傳輸模型

POST /groundwater/solute-transport

計算地下水中污染物傳輸濃度 (C = M / Q_gw)

6. 風險評估模型

POST /groundwater/risk-assessment

計算慢性日攝入量（CDI）與健康風險

Request:

{
  "C": 0.05,   // 濃度 (mg/L)
  "IR": 2,     // 攝入率 (L/day)
  "EF": 350,   // 暴露頻率 (days/yr)
  "ED": 30,    // 暴露年限 (years)
  "BW": 70,    // 體重 (kg)
  "AT": 25550  // 平均時間 (days)
}

Response:

{
  "CDI": 0.000082,
  "risk": 4.5e-6,
  "risk_cost_ntd": 27000
}

7. 土壤採樣數計算

POST /groundwater/sample-size

統計學方法計算所需樣本數 (n = (Z × σ / E)²)

8. 污染傳輸模型

POST /groundwater/pollution-transport

模擬污染物在土壤和地下水中的遷移路徑

9. 水質評分

POST /groundwater/water-quality

綜合評估水質參數並給出 0–100 分數

地下水工具端點 /indicators/groundwater-analysis/...

10. 水力導水性估算（Hydraulic Conductivity）

POST /indicators/groundwater-analysis/calc-conductivity

依粒徑或孔隙率估算 K 值，支援 Hazen 法、Kozeny-Carman 法、USCS 質地查表法

Request:

{
  "method": "hazen",  // hazen / kozeny_carman / texture
  "d10": 0.15,        // 有效粒徑 mm（Hazen 法）
  "porosity": 0.35,   // 孔隙率（Kozeny-Carman 法）
  "texture": "sandy_loam" // 質地（texture 法）
}

Response:

{
  "K_cm_s": 0.0148,
  "K_m_day": 12.79,
  "method_used": "Hazen",
  "applicable_range": "d10: 0.1~3mm",
  "note": "適用砂質含水層"
}

生態系統 API（12 個）

生態系統服務計算 /api/calculations/ecosystem/...

1. 總經濟價值（TEV）

POST /ecosystem/tev

計算供給、調節、支持、文化四大服務的總價值

Request:

{
  "provisioning": 500000,
  "regulating": 800000,
  "supporting": 300000,
  "cultural": 200000
}

Response:

{
  "total_economic_value": 1800000,
  "provisioning_percent": 27.78,
  "regulating_percent": 44.44,
  "supporting_percent": 16.67,
  "cultural_percent": 11.11
}

2. 淨現值（NPV）

POST /ecosystem/npv

計算專案淨現值與效益成本比（BCR）

3. 服務瀑布模型

POST /ecosystem/cascade

追蹤生態結構→過程→功能→效益→價值的串連

4. 空間估值

POST /ecosystem/spatial-valuation

不同土地利用類型的空間估值

5. 替代成本法

POST /ecosystem/replacement-cost

計算用技術替代生態系統服務的成本

6. 水源涵養服務

POST /ecosystem/water-yield

計算水文服務產出與價值 (Y = (P − AET) × A × φ)

7. 綜合估值

POST /ecosystem/integrated

整合多種服務的綜合評估

生態系統工具端點 /indicators/ecosystem-analysis/... 及 /indicators/

8. 服務瀑布有效組合查詢

GET /indicators/ecosystem-analysis/cascade-combos

回傳 16 組有效（生態系, 服務類型）組合及標籤，用於瀑布模型下拉選單

9. 生態系服務瀑布模型計算

POST /indicators/ecosystem-analysis/cascade-calculate

計算完整六段鏈：結構→過程→功能→服務→效益→價值，含 NPV 與文獻來源

Request:

{
  "ecosystem_type": "coastal_wetland",
  "service_type": "carbon_sequestration",
  "area_ha": 30.5,
  "discount_rate": 0.03,
  "time_horizon": 30
}

Response:

{
  "stages": [
    {"label": "結構", "value": 120, "unit": "g C/m²/yr"},
    {"label": "過程", ...},
    {"label": "價值", "value": 2847000, "unit": "NT$/yr"}
  ],
  "npv_ntd": 59820000,
  "reference": "Fourqurean 2012"
}

10. Double Counting 矩陣檢核

POST /indicators/double-counting-check/api

輸入已選服務清單，回傳潛在重疊組合與建議，避免重複計價

Request:

{
  "selected_services": [
    "carbon_sequestration",
    "biodiversity",
    "water_purification"
  ]
}

Response:

{
  "overlap_pairs": [
    {"a": "碳匯", "b": "生物多樣性", "risk": "high"}
  ],
  "warning_count": 1,
  "recommendation": "碳匯+生物多樣性建議..."
}

11. 基線情境與增量估值

POST /indicators/baseline-increment/calculate

計算保育/復育/開發情境相對基線的增量價值（Low/Base/High 三情境）

Request:

{
  "service_type": "carbon_sequestration",
  "baseline_value": 1200000,
  "action_scenario": "restoration",
  "area_ha": 30.5,
  "discount_rate": 0.03,
  "time_horizon": 30
}

Response:

{
  "incremental_low": 850000,
  "incremental_base": 1540000,
  "incremental_high": 2230000,
  "npv_base": 32400000,
  "scenario_label": "復育情境"
}

12. 效益轉移參數庫查詢

GET /benefit-transfer/api/lookup

依服務類型查詢 Tier 1/2/3 效益轉移參數，回傳台灣本地研究與亞洲研究數據

Query Params:

?service_type=carbon_sequestration
&ecosystem_type=wetland  (optional)
&tier_max=2              (optional, default 3)

Response:

{
  "params": [
    {
      "id": 3,
      "name": "台灣紅樹林碳匯",
      "unit_value": 850,
      "unit": "NT$/tCO2e",
      "tier": 1,
      "source": "林務局 2022"
    }
  ],
  "count": 4
}

整合評估框架

GEP 框架與 InVEST 模型的計算由各工具頁面內部處理，透過互動式介面操作，不提供外部 REST API 端點。

GEP 框架

生態系產品總值計算
操作頁面：/gep/

InVEST 模型

Stanford/NatCap 生態服務量化
操作頁面：/invest/

第三層：財務╱市場層 9 個端點

自然碳匯 MRV API（8 個）

碳匯計算 /api/calculations/carbon/...

1. 植被生長模型

POST /carbon/vegetation-growth

預測不同林齡的生物質累積量

2. 生態系碳存量

POST /carbon/ecosystem-stock

計算整體生態系統地上/地下/土壤碳存量

3. MRV 機制評估

POST /carbon/mrv

監測、報告、驗證機制與成本評估

Request:

{
  "carbon_stock": 1000,
  "sequestration_rate": 50,
  "reporting_period": 5,
  "verification_status": "verified",
  "area_ha": 10
}

Response:

{
  "creditable_carbon": 250,
  "uncertainty": 0.15,
  "mrv_cost_ntd": 50000,
  "cost_per_ton": 200
}

4. 生物質-碳轉換

POST /carbon/biomass-conversion

生物質轉換為碳存量與 CO₂ 當量 (C = Biomass × 0.5, CO₂e = C × 3.67)

5. 年度固碳量

POST /carbon/sequestration

計算年度固碳速率

6. 基線情境分析

POST /carbon/baseline

計算相對基線的減碳效益與碳權價值

7. 碳權估值

POST /carbon/credit-valuation

計算碳權總價值與年度收益

8. 完整專案分析

POST /carbon/complete-analysis

綜合分析碳匯專案的所有指標與經濟效益

Request:

{
  "area_ha": 10,
  "age_years": 15,
  "aboveground_biomass_tons_ha": 150,
  "belowground_biomass_tons_ha": 30,
  "carbon_price": 300,
  "project_years": 30,
  "discount_rate": 0.03
}

Response (部分):

{
  "current_carbon_stock_tons_C": 900,
  "current_co2e_tons": 3303,
  "annual_sequestration_co2e_tons": 220,
  "total_revenue_npv_ntd": 15234000
}

自然資本整合估值 API（1 個）

整合估值計算

POST /valuation/calculate

整合七種棲地類型 × 三情境（不佳/普通/優良），計算 TEV + 碳匯資產 + UK BNG 補償潛力

Request:

{
  "habitat_type": "coastal_wetland",
  "area_ha": 1.0,
  "scenario": "good",  // poor / fair / good
  "discount_rate": 0.03,
  "time_horizon": 30
}

Response:

{
  "tev_annual_ntd": 793000,
  "tev_npv_ntd": 18700000,
  "carbon_asset_ntd": 1250000,
  "bng_units": 15.0,
  "bng_compensation_ntd": 6750000,
  "total_ntd": 26700000
}

使用範例

JavaScript (Fetch API)

fetch('/api/calculations/biodiversity/sar', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ area_before: 1.0, area_after: 1.5, unit_cost: 30000 })
})
.then(r => r.json())
.then(data => {
  if (data.success) console.log('Result:', data.result);
  else console.error('Error:', data.error);
});

Python (Requests)

import requests

url = 'http://23.239.8.18:5003/api/calculations/carbon/complete-analysis'
data = {
    'area_ha': 10, 'age_years': 15,
    'aboveground_biomass_tons_ha': 150,
    'belowground_biomass_tons_ha': 30,
    'carbon_price': 300, 'project_years': 30, 'discount_rate': 0.03
}
result = requests.post(url, json=data).json()
if result['success']:
    print('NPV:', result['result']['total_revenue_npv_ntd'])

cURL

curl -X POST http://23.239.8.18:5003/api/calculations/ecosystem/tev \
  -H "Content-Type: application/json" \
  -d '{"provisioning":500000,"regulating":800000,"supporting":300000,"cultural":200000}'

健康檢查端點

GET /api/calculations/health

{
  "status": "healthy",
  "total_models": 45,
  "timestamp": "2026-06-23T12:00:00"
}

注意事項

所有 API 端點皆需登入驗證（Session-based）
建議呼叫前先確認 /api/calculations/health 服務可用
所有貨幣單位為新台幣（NTD）
API 回應時間通常 < 2 秒