Open API version 2.01

本API(v2版)自2020年1月1日啟用,原API 1.0版於2020年4月1日關閉,請舊版使用者立即升級。謝謝。

修改歷程紀錄

  • 2020.6.22 API 2.01 啟用 (部分欄位名更動,參見公告
  • 2020.1.1 API 2.0 啟用
  • 2018.12 API 1.0上線

API基本說明

TBN的Open API為公開服務,對所有人開放,惟請注意:

  • 為保護敏感物種,資料進行了必要的模糊化處理,若使用者有取得未模糊化資料之需求,可申請限制型 API
  • 為保護個人隱私,資料內未含有觀測者個人資料。
  • API目的為供機器自動處理,非供直接閱讀。
  • 本API僅提供JSON格式。

API基本架構

服務網址

本API的一般性服務網址為 https://www.tbn.org.tw/api/{version}/{type}/{parameters} ,其中:

  • {version}: API版本,本版本為v2。
  • {type}: API服務類型,本版本支援species、dataset與occurrence三類。
  • {parameters}: 查詢參數。查詢參數為查詢條件(Query string),其內容依各服務而不同。

服務類型

本API提供三種服務類型:

species 物種查詢

本類型提供TBN物種資料庫查詢服務。透過本類型服務,可以物種名(含別名)關鍵字及TBN物種UUID查詢TBN物種(含高階分類群)。

本類型取得之資訊,如TBN物種UUID,可用於觀測紀錄查詢。

dataset 資料集查詢

本類型提供TBN收錄資料集查詢服務。透過本類型服務,可以資料集標題關鍵字及TBN資料集UUID取得TBN資料集資訊。

本類型取得之資訊,如TBN資料集UUID,可用於觀測紀錄查詢。

occurrence 觀測記錄查詢

本類型提供TBN收錄觀測記錄查詢。本服務會進行部分資訊模糊化,如果你有取得模糊化資料之需求,請申請限制性API服務

共通查詢參數

分頁與筆數限制

因效能考量,本API限制單一請求至多回傳300筆資料,你可以透過分頁參數進行多次請求以取得全部查詢資料。分頁參數為:

參數 說明
limit 限制每頁回傳筆數,預設為300,至多為300
offset 指定每頁起始編號

每次API取得之資料中,如有下一分頁資料,會包含取得下一分頁之網址,可用該網址遞迴取得全部資料。

回傳格式

本API回傳符合條件的JSON結果物件(Object),其回傳格式為:

{
    "meta": {
        "total": (int)符合查詢條件全部筆數
    },
    "links": {
        "self": (string)本頁網址,
        "next": (string)下一分頁網址
    },
    "data": (Array) [結果陣列],
}

使用規範

本API採「政府資料開放授權條款」授權公眾使用。

後續發展

TBN API以開放並盡可能釋出原始資料為目標。對本API有任何建議,請不吝告訴我們

物種查詢

TBN 提供物種資料庫的查詢服務。透過本類型服務,可用物種名(含別名)關鍵字及TBN物種UUID查詢TBN物種(含高階分類群)。

本類型取得之資訊,如TBN物種UUID,可用於觀測紀錄查詢。

物種名查詢參數

路徑: species

查詢條件: ?name={string}

說明: 查詢TBN內符合查詢條件{string}的所有物種,查詢範圍包括學名、俗名、異名。本查詢為模糊查詢,即會回傳名稱任一部份符合查詢條件者。

範例:

服務網址:https://www.tbn.org.tw/api/v2/species?name=山艾&limit=20

說明:找所有名字中有「山艾」的物種

回傳

{
    "meta": {
        "total": 6
    },
    "links": {
        "self": "https://www.tbn.org.tw/api/v2/species?name=%E5%B1%B1%E8%89%BE&limit=20",
        "next": ""
    },
    "data": [
        {
            "taxonUUID": "7fd8cbf6-4128-4215-989f-4bcfc328f693",
            "taxonName": "<span class=\"name-tw\">高山艾</span> <span class=\"name-s\"><i>Artemisia oligocarpa</i> Hayata</span>",
            "scientificName": "Artemisia oligocarpa Hayata",
            "vernacularName": "高山艾",
            "taxonRank": "種",
            "class": "種子植物綱  Class Spermatopsida",
            "family": "菊科  Family Asteraceae",
            "protectedStatusTW": "",
            "categoryRedlistTW": "暫無危機(LC, Least Concern)",
            "categoryIUCN": "",
            "sensitiveState": "",
            "taicolNameCode": ""
        },
        ......
    ]
}


物種UUID查詢參數

路徑: species

查詢條件: ?UUID={string}

說明: 取得TBN內物種UUID為{string}的物種資訊。

範例:

服務網址:https://www.tbn.org.tw/api/v2/species?uuid=7fd8cbf6-4128-4215-989f-4bcfc328f693

說明:取得「uuid= 7fd8cbf6-4128-4215-989f-4bcfc328f693」(高山艾)的物種資訊

回傳

{
    "meta": {
        "total": 1
    },
    "links": {
        "self": "https://www.tbn.org.tw/api/v2/species?uuid=7fd8cbf6-4128-4215-989f-4bcfc328f693",
        "next": ""
    },
    "data": [
        {
            "taxonUUID": "7fd8cbf6-4128-4215-989f-4bcfc328f693",
            "taxonName": "<span class=\"name-tw\">高山艾</span> <span class=\"name-s\"><i>Artemisia oligocarpa</i> Hayata</span>",
            "scientificName": "Artemisia oligocarpa Hayata",
            "vernacularName": "高山艾",
            "taxonRank": "種",
            "class": "種子植物綱  Class Spermatopsida",
            "family": "菊科  Family Asteraceae",
            "protectedStatusTW": "",
            "categoryRedlistTW": "暫無危機(LC, Least Concern)",
            "categoryIUCN": "",
            "sensitiveState": "",
            "taicolNameCode": ""
        }
    ]
}

資料集查詢

TBN 提供TBN收錄資料集查詢服務務。透過本類型服務,可以資料集標題關鍵字及TBN資料集UUID取得TBN資料集資訊。

本類型取得之資訊,如資料集UUID,可用於觀測紀錄查詢。

資料集名查詢參數

路徑: dataset

查詢條件: ?name={string}

說明: 查詢TBN內標題含有查詢條件{string}的所有資料集。本查詢為模糊查詢,即會回傳名稱任一部份符合查詢條件者。

範例:

服務網址:https://www.tbn.org.tw/api/v2/dataset?name=植

說明:找所有名字中有「植」的資料集

回傳

{
    "meta": {
        "total": 5
    },
    "links": {
        "self": "https://www.tbn.org.tw/api/v2/dataset?name=%E6%A4%8D",
        "next": ""
    },
    "data": [
        {
            "datasetName": "植物調查及物候觀察",
            "datasetTaxonGroup": "被子植物、蕨類、石松類、裸子植物",
            "datasetLicense": "",
            "datasetPublisher": "TBN研究資料管理中心",
            "datasetAuthor": "沈明雅、張慧玲、柯智仁、郭貴嵐",
            "datasetUUID": "248d6799-bb66-40a5-b7ba-b45bbb818ddc",
            "datasetURL": "https://www.tbn.org.tw/dataset/248d6799-bb66-40a5-b7ba-b45bbb818ddc",
            "datasetDataFrom": "tbnra",
            "datasetCreated": "2019-08-27T02:40:26Z",
            "datasetMetadataLastModified": "2019-11-26T08:11:53Z",
            "datasetDateCoverage": "2006-04-23 ~ 2019-11-24",
            "datasetLastImport": "2019-12-12T12:24:52Z",
            "occurrenceCount": "12987"
        },
        ......
    ]
}

資料集UUID查詢參數

路徑: dataset

查詢條件: ?UUID={string}

說明: 取得TBN內資料集UUID為{string}的資料集資訊。

範例:

服務網址:https://www.tbn.org.tw/api/v2/dataset?uuid=248d6799-bb66-40a5-b7ba-b45bbb818ddc

說明:取得「uuid= 7fd8cbf6-4128-4215-989f-4bcfc328f693」的資料集資訊

回傳

{
    "meta": {
        "total": 1
    },
    "links": {
        "self": "https://www.tbn.org.tw/api/v2/dataset?uuid=248d6799-bb66-40a5-b7ba-b45bbb818ddc",
        "next": ""
    },
    "data": [
        {
            "datasetName": "植物調查及物候觀察",
            "datasetTaxonGroup": "被子植物、蕨類、石松類、裸子植物",
            "datasetLicense": "",
            "datasetPublisher": "TBN研究資料管理中心",
            "datasetAuthor": "沈明雅、張慧玲、柯智仁、郭貴嵐",
            "datasetUUID": "248d6799-bb66-40a5-b7ba-b45bbb818ddc",
            "datasetURL": "https://www.tbn.org.tw/dataset/248d6799-bb66-40a5-b7ba-b45bbb818ddc",
            "datasetDataFrom": "tbnra",
            "datasetCreated": "2019-08-27T02:40:26Z",
            "datasetMetadataLastModified": "2019-11-26T08:11:53Z",
            "datasetDateCoverage": "2006-04-23 ~ 2019-11-24",
            "datasetLastImport": "2019-12-12T12:24:52Z",
            "occurrenceCount": "12987"
        }
    ]
}

觀測記錄搜尋

TBN 提供觀測記錄搜尋服務。本服務會進行部分資訊模糊化,但如果你仍有取得模糊化資料之需求,請申請限制性API服務。

查詢參數 說明 範例網址
tbnID={int} 取得tbnID為{int}的觀測記錄資訊。注意: tbnID為TBN觀測記錄唯一識別碼,同時指定其他查詢條件時,將會忽略其他條件。 https://www.tbn.org.tw/api/v2/occurrence?tbnID=5723686
taxonUUID={string} 取得物種UUID為{string}的觀測記錄資訊。 https://www.tbn.org.tw/api/v2/occurrence?taxonUUID=7fd8cbf6-4128-4215-989f-4bcfc328f693&limit=20
datasetUUID={string} 取得TBN內資料集UUID為{string}的觀測記錄資訊。 https://www.tbn.org.tw/api/v2/occurrence?datasetUUID=248d6799-bb66-40a5-b7ba-b45bbb818ddc&limit=20
eventDate={string} 取得TBN內觀測日期為{string}的觀測記錄資訊。  
● eventDate={yyyy-mm-dd} 年月日查詢 https://www.tbn.org.tw/api/v2/occurrence?eventDate=2018-07-16&limit=20
● eventDate={yyyy-mm} 年月查詢 https://www.tbn.org.tw/api/v2/occurrence?eventDate=2018-07&limit=20
● eventDate={yyyy} 年查詢 https://www.tbn.org.tw/api/v2/occurrence?eventDate=2018&limit=20
● eventDate={yyyy~yyyy} 範圍查詢,可指定年月日、年月、年範圍 https://www.tbn.org.tw/api/v2/occurrence?eventDate=2019~2020&limit=20
eventPlaceAdminarea={string} 行政區名查詢,本查詢支援部分查詢 https://www.tbn.org.tw/api/v2/occurrence?eventPlaceAdminarea=南投&limit=20
boundedBox={latlng latlng} 四界(boundedBox)查詢,請指定右上-左下座標 https://www.tbn.org.tw/api/v2/occurrence?boundedBox=23.85,120.81 23.81,120.77&limit=20
decimalLatLng={latlng +} 多邊形座標查詢 https://www.tbn.org.tw/api/v2/occurrence?decimalLatLng=24.50,118.42 24.47,118.39 24.45,118.42 24.47,118.45 24.51,118.44&limit=20

複合查詢

除tbnID外,各查詢參數均可做聯集查詢。如以下網址查詢"植物調查及物候觀察"資料集中"大花咸豐草"的觀測紀錄

https://www.tbn.org.tw/api/v2/occurrence?taxonUUID=9164c378-ef51-4423-a166-1a979c73a97d&datasetUUID=248d6799-bb66-40a5-b7ba-b45bbb818ddc&limit=20

回傳範例:

{
    "meta": {
        "total": 186
    },
    "links": {
        "self": "https://www.tbn.org.tw/api/v2/occurrence?taxonUUID=9164c378-ef51-4423-a166-1a979c73a97d&datasetUUID=248d6799-bb66-40a5-b7ba-b45bbb818ddc&limit=20",
        "next": "https://www.tbn.org.tw/api/v2/occurrence?taxonUUID=9164c378-ef51-4423-a166-1a979c73a97d&datasetUUID=248d6799-bb66-40a5-b7ba-b45bbb818ddc&limit=20&offset=5725974"
    },
    "data": [
        {
            "tbnID": "5723679",
            "occurrenceUUID": "9ab80d19-967a-4cbf-8748-e871e0aee3e3",
            "created": "2018-07-16T02:22:57Z",
            "modified": "2019-12-02T13:57:49Z",
            "proposedTaxon": "大花咸豐草",
            "scientificName": "Bidens pilosa L. var. radiata (Sch.Bip.) Sherff",
            "vernacularName": "大花咸豐草",
            "taxonUUID": "9164c378-ef51-4423-a166-1a979c73a97d",
            "coordinateUncertaintyInMeters": "",
            "coordinatePrecision": "",
            "establishmentMeans": "野⽣",
            "decimalLatitude": "",
            "decimalLongitude": "",
            "eventPlaceAdminarea": null,
            "eventDate": "2018-06-10T04:15:00Z",
            "basisOfRecord": "HumanObservation",
            "identificationVerificationStatus": "已鑑定",
            "individualCount": "1",
            "organismQuantity": "",
            "organismQuantityType": "",
            "taxonGroup ": "被子植物",
            "license": "CC BY 4.0+",
            "dataset_publisher": "TBN研究資料管理中心",
            "dataset_author": "沈明雅、張慧玲、柯智仁、郭貴嵐",
            "dataSensitiveIndicator": "",
            "datasetName": "植物調查及物候觀察",
            "datasetUUID": "248d6799-bb66-40a5-b7ba-b45bbb818ddc",
            "datasetURL": "https://www.tbn.org.tw/dataset/248d6799-bb66-40a5-b7ba-b45bbb818ddc",
            "eventID": null
        },
        ...
    ]
}