本API(1.0版)於2020年4月1日關閉,現行版本請參見API說明頁。
API基本說明
TBN的Open API為公開服務,對所有人開放,惟請注意:
- 為保護敏感物種,資料進行了必要的模糊化處理
- 為保護個人隱私,資料內未含有觀測者個人資料
- API目的為供機器間自動處理,非供直接閱讀,本API僅提供JSON
- 本API以 GBIF API v1(http://api.gbif.org/v1/) 為設計藍本,在API服務網址設計時盡可能和GBIF採取相同方式,惟因TBN目標和設計理念和GBIF不盡相同,本API應視為獨立規範。
API基本架構
服務網址
TBN API提供基本的RESTful服務,且僅支援以GET方式取得資料。API的一般性服務網址為
https://www.tbn.org.tw/api/{version}/{type}/{parameters}
其中
{version}: API版本,目前為v1
{type}: API服務類型,目前為species與occurrence二類
{parameters}: 查詢參數。查詢參數可能為網址路徑(path)或查詢條件(Query string),其內容依各服務而不同,請參閱以下說明。
服務類型
本API提供兩種服務類型:
species: 提供物種名查詢,本類型目的並非在提供物種資料庫的查詢服務,而僅為提供其他類型(本版本僅包含occurrence)查詢前,能取得關於物種的標準名查詢。如有物種查詢需求,請至台灣物種名錄TaiBNET(http://taibnet.sinica.edu.tw/ )。
occurrence: 提供TBN觀測記錄查詢,如前述,本服務會進行部分資訊遮蔽,在多數的使用情境此遮蔽不會有顯著分析上的偏差,但如果你仍有取得遮蔽資料之需求,請申請限制性API服務。
共通查詢參數
分頁與筆數限制
因系統效能考量,本API限制單一請求至多回傳1000筆資料,你可以透過分頁參數進行多次請求以取得全部查詢資料。分頁參數為:
參數 | 說明 |
---|---|
limit | 限制每頁回傳筆數,至多1000 |
offset | 指定每頁記錄跳過筆數,如設定limit為30,offset為20,會回傳符合條件中第21~50筆資料 |
範圍查詢
部分查詢條件支援範圍查詢,請以半形波浪號(~)分隔起、迄範圍,如時間指定1995至2005資料時,其參數為「eventDate:1995~2005」。
多條件查詢
本API支援交集多條件查詢,多條件查詢時請以半形加號(+)分隔,如欲查詢物種為japalura swinhonis且觀測地點為花蓮縣,其參數為「biotaxonname:japalura swinhonis+adminarea:花蓮縣」
回傳格式
本API回傳符合條件的JSON結果物件(Object),其回傳格式為:
{ "count": (int) 符合條件總數, "offset": (int) 跳過筆數, "limit" : (int) 本頁最多筆數, "endOfRecords": (boolean: true | false) 是否為最後一頁, "results": (Array) [結果陣列], }
使用規範
本API採「政府資料開放授權條款」授權公眾使用。
後續發展
TBN API以開放並盡可能釋出原始資料為目標,如果任何對本API的建議,請不吝告訴我們。
物種搜尋
TBN 目前提供簡易的物種名稱搜尋服務。本服務目的並非在提供物種資料庫的查詢服務,而僅為提供其他類型查詢前,能取得關於物種的標準名。如有物種查詢需求,請至台灣物種名錄TaiBNET(http://taibnet.sinica.edu.tw/)。
查詢參數
路徑:species/match
查詢條件:?name={string}
說明
查詢TBN內符合查詢條件{string}的所有物種,查詢範圍包括學名、俗名、異名。本查詢為模糊查詢,即會回傳名稱任一部份符合查詢條件者
範例
服務網址
https://www.tbn.org.tw/api/v1/species/match?name=攀蜥
回傳
{ count: 8, offset: 0, limit: 1000, endOfRecords: true, results: [ ["name": "呂氏攀蜥", "scientific name": "Japalura luei",], ["name": "斯文豪氏攀蜥", "scientific name": "Japalura swinhonis",], ["name": "牧氏攀蜥", "scientific name": "Japalura makii",], ["name": "短肢攀蜥", "scientific name": "Japalura brevipes",], ["name": "箕作氏攀蜥", "scientific name": "Japalura swinhonis",], ["name": "黃口攀蜥", "scientific name": "Japalura polygonata",], ["name": "斯氏攀蜥", "scientific name": "Japalura swinhonis",], ["name": "黃口攀蜥", "scientific name": "Japalura polygonata xanthostoma",] ] }
觀測記錄搜尋
TBN 提供觀測記錄搜尋服務。本服務會進行部分資訊遮蔽,在多數的使用情境此遮蔽不會有顯著分析上的偏差,但如果你仍有取得遮蔽資料之需求,請申請限制性API服務。
查詢參數
路徑: occurrence
查詢條件: ?{key}={value}
說明
查詢TBN內符合查詢條件的所有觀測記錄,查詢條件支援交集多條件查詢,多條件查詢時請以半形加號(+)分隔。目前支援的查詢條件如下表:
查詢條件 | 值 | 說明 | 備註 |
---|---|---|---|
tbnid | ID | TBN觀測記錄唯一識別碼 | tbnid 為唯一識別碼,同時指定其他查詢條件時,將會忽略其他條件 |
scientificName | 文字清單 | 學名 | |
eventDate | 時間 | 觀測時間 | 支援範圍查詢,支援格式包括西元年(如 2010)、年月(2010-1)、年月日(2010-1-30)。範圍查詢時起迄時間必須為同一格式,如2010~2015 |
eventPlaceAdminarea | 文字清單 | 觀測地行政區 | |
decimalLatLng | 數字座標 | 觀測座標 | 數字座標為成對的 緯度,經度,觀測座標支援矩形範圍查詢,如 23.00,120.5~23.10,120.6 |
範例
服務網址
https://www.tbn.org.tw/api/v1/occurrence?tbnId=5714634
回傳
{ "count": 1, "offset": 0, "limit": 10, "endOfRecords": true, "with_restrict": false, "results": [ { "tbnId": "5679479", "occurrenceID": "tw:org:tbn:ra:occurrence:4644311", "basisOfRecord": "Array", "eventDate": "2018-07-26T06:00:00Z", "decimalLatitude": "23.9244", "decimalLongitude": "120.80083", "eventPlaceAdminarea": "南投縣中寮鄉", "isIdentified": "已鑑定", "scientificName": "Nephila pilipes", "vernacularName": "人面蜘蛛", "group": "蜘蛛類", "individualCountMin": "", "dataset": "蜘蛛公民科學調查", "datasetURL": "https://loc.tbn.org.tw/dataset/8188032" } ] }