[簡介] Eco API - 生物出現紀錄與微塑膠資料介接
發佈日期：2024-10-01 | 最後更新：2024-11-01 | API 版本： v1.4
ODB 於今年推出新版生物資料庫與微塑膠資料庫，並同時推出了 Eco API (https://api.odb.ntu.edu.tw/ecoapi/) 提供各界介接，以促進資料的開放與應用。Eco API 以 fastify.js 框架開發，並搭配 Swagger UI 生成簡明的說明與測試頁面 Eco API Document。在 Document 中點選任一端點可開啟其專屬區塊，區塊內列有詳細的端點和參數說明，若點擊區塊右上角 Try it out 按鈕將切換為測試模式，使用者可以輸入參數、點擊區塊下方的 Execute 執行查詢、取得資料。資料引用方法請參考回傳資料欄位 bibliographicCitation，或是 ODB 引用說明。
*注意：若查詢大量資料將導致此 Document 頁面回應緩慢，因此測試時建議輸入參數縮小查詢範圍，欲查詢大量資料建議直接介接 API。
生物資料
生物資料端點包含基礎查詢功能，例如查詢生物類群名稱、出現紀錄；以及進階分析功能，如計算網格化物種組成、統計區域物種名錄，以下一一說明：
1. 查詢生物類群名稱 (學名或俗名)
在 Eco API 中我們透過生物類群學名或是 AphiaID 來查詢資料。因此若是不知道該類群的學名或 AphiaID 就先來端點 /bio/taxon/name/ 查查吧！可以輸入學名或是俗名查詢，也可以用 * 作為萬用字元 (wildcard) 進行匹配，我們的學名 (scientificName) 和外文俗名 (commonName) 資料皆依照 WoRMS 資料庫為準，而中文俗名 (chineseName, chineseNameAlternative) 則是介接自 TaiCOL 資料庫。
*僅能查詢資料庫中具有出現紀錄的類群名稱資訊。
2. 查詢生物出現紀錄
確認生物類群學名或是 AphiaID 後，便可透過端點 /bio/occurrence/name/ 或是 /bio/occurrence/id/ 來介接生物類群的出現紀錄，資料可依參數經緯度、時間、季節、主題、分類階層、資料來源、作者、是否為開放申請資料來篩選。需注意的是，端點將回傳您查詢的生物類群以及其下所有子類群的出現紀錄；若加上分類階層參數 rank，便僅會回傳指定階層 (含) 以下的出現紀錄。舉例來說，查詢類群 Copepoda (橈足綱)，其下目、科、屬、種…等出現紀錄都會回傳；若加上指定階層「種」，則只會回傳橈足綱之中鑑定至種、亞種的出現紀錄。
*詳細出現紀錄資料介紹請參考頁面資料庫。
3. 計算網格化物種組成
針對單一生物類群，除了出現紀錄以外，我們可以透過端點 /bio/grid/id/ 計算網格內的物種組成。資料可依參數經緯度、時間、季節、主題、資料來源、作者、是否為開放申請資料來篩選。需注意的是，除輸入生物類群的 AphiaID 以外，還須輸入參數 inRank 指定要以哪個階層計算物種組成，當然這一定得選一個原生物類群之下的階層，否則計算出的資料便沒有意義。例如，查詢 AphiaID 為 1080 的類群 (Copepoda 橈足綱)，並且設定階層參數 inRank 為 order (目)，便會計算每個網格 Calanoida (哲水蚤目)、Cyclopoida (劍水蚤目)、Harpacticoida (猛水蚤目)…等目的組成百分比。端點回傳資料分為 grid 和 metadata 兩部分，grid 即網格化計算結果，metadata 則提供簡易統計資訊給使用者參考。
*若輸入某個 AphiaID (生物類群) 但不論切換甚麼階層計算皆回傳空資料，代表該類群之中沒有鑑定至更細階層的出現紀錄可進行運算。
https://api.odb.ntu.edu.tw/ecoapi/bio/grid/id/1080?size=2&inRank=order
4. 統計區域物種名錄
除了針對單一類群的查詢或計算，Eco API 也提供端點 /bio/checklist 統計指定區域內的物種名錄。資料可依參數經緯度、時間、季節、主題、分類階層、資料來源、作者、是否為開放申請資料來篩選。需注意目前僅開放多邊形區域的統計，而相應參數 polygon 允許輸入的格式有兩種，第一種是經緯度陣列 [lat1, lon1, lat2, lon2, lat3, lon3,…]；第二種是 GeoJSON 物件，並且限 Polygon (Feature)。端點回傳資料分為三部分，checklistSummary 統計七大階層涵蓋類群數，checklist 即為物種名錄，metadata 則提供簡易統計資訊給使用者參考。
https://api.odb.ntu.edu.tw/ecoapi/bio/checklist?rank=species&polygon=[119,23,120,23,120,24,119,24]
微塑膠資料
微塑膠濃度提供端點 /microplastic 介接，可依參數經緯度、時間、季節、採樣環境、資料來源、作者、濃度等級來篩選。端點回傳資訊包含濃度等級 (densityClass/densityClassChinese)、採樣環境 (medium/mediumChinese)、採樣方法 (samplingProtocol)。需注意的是，微塑膠濃度可能因採樣環境和方法不同而有極大差異，使用資料前應詳閱原始資料來源並謹慎評估之。
*微塑膠資料庫介紹請參考此篇文章。
https://api.odb.ntu.edu.tw/ecoapi/microplastic?season=8&medium=o&level=vl
參數代碼
如果試用過 Eco API 的話應該已經發現，為求輸入便利，許多參數中我們皆透過代碼來指定查詢內容。為此我們另外提供端點 /option/bio/ 和 /option/microplastic/ 揭示生物和微塑膠資料中的參數代碼意涵。端點回傳代碼 (code) 和其相應的中/英文說明 (optionChinese/option)。
https://api.odb.ntu.edu.tw/ecoapi/option/microplastic/medium
Chinese 
English