Open 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=995~2005」。

多條件查詢

本API支援交集多條件查詢,多條件查詢時請以標準REST方式加入,即以&分隔,如欲查詢物種為japalura swinhonis且觀測地點為花蓮縣,其參數為「scientificName=apalura 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=637055
回傳

{
  count: 1,
  offset: 0,
  limit: 1000,
  endOfRecords: true,
  with_restrict: false,
  results: [
    {
      tbnId: "637055",
      basisOfRecord: "Human Observation",
      eventDate: "2017-08-04 07:35",
      decimalLatitude: "23.83",
      decimalLongitude: "120.8",
      eventPlaceAdminarea: "南投縣集集鎮",
      isIdentified: "已鑑定",
      scientificName: "Japalura swinhonis",
      twName: "斯文豪氏攀蜥",
      group: "爬蟲類",
      individualCountMin: "3",      
      dataset: "特有生物研究保育中心生態教育園區生物多樣性觀測紀錄",
      datasetURL: "https://www.tbn.org.tw/node/841998",
      photos: [
        "https://www.tbn.org.tw/sites/tbn/files/occurrence/637055_3.dbd663c3-4ce6-410c-85b6-93b5ecf654ef.jpg",
        "https://www.tbn.org.tw/sites/tbn/files/occurrence/637055_2.c1793ef8-2324-46bc-8bc5-8b60aff2174d.jpg",
        "https://www.tbn.org.tw/sites/tbn/files/occurrence/637055_0.114bdc74-74be-481b-bd57-bcd12f6915fb.jpg",
        ],
    }
  ]
}