移至主內容

Occurrence API 2.5.1

Occurrence API 2.5.1版即刻推出,本版本僅作小幅度修改,部分欄位將於2.6版移除,請使用本API者先行準備。細部更動見於文件中。

簡介

本文件由農業部生物多樣性研究所編製,描述所屬台灣生物多樣性網絡(Taiwan Biodiversity Network,TBN)之觀測紀錄(occurrence)開放與限制型API規格。

服務類型

本API之觀測紀錄查詢同時適用於開放與限制型API。開放API對敏感資料會進行部分資訊模糊化以保護敏感物種。限制性則可取得未模糊化資訊。限制性API需另向本API管理單位申請。

查詢參數

參數型態

  • 時間:字串,格式為西元10碼+24小時制精度至分之5碼格式,即YYYY-MM-DD HH:MM,台灣時區
  • UUID:字串,RFC 4122,需含斷字符號共36個字元
  • 數字
  • 文字

參數名稱

參數中文名

型態

說明

範例網址

UUID

紀錄UUID

UUID

TBN觀測紀錄UUID

https://www.tbn.org.tw/api/v25/occurrence?UUID=0f196fd7-9c63-4ac5-b442-a60735d3cbe9&limit=20

modified

最後修改時間

時間

格式YYYY-MM-DD HH:II,指定時間之後修改的資料。例如:要查詢2022年2月之後修改的資料,請輸入2022-02-01 00:00

https://www.tbn.org.tw/api/v25/occurrence?modified=2022-01-07%2000:00&limit=20

taxonUUID

物種UUID

UUID

TBN物種UUID

https://www.tbn.org.tw/api/v25/occurrence?taxonUUID=f8947246-6152-439c-9a67-a6b1422941b4&limit=20

datasetUUID

資料集UUID

UUID

TBN資料集UUID

https://www.tbn.org.tw/api/v25/occurrence?datasetUUID=422ce21b-b706-44d9-a022-292b05314f63&limit=20

eventDate

觀測日期

文字

觀測日期支援以下幾種形式:

 

● eventDate={YYYY-MM-DD}

 

YYYY-MM-DD

年月日查詢

https://www.tbn.org.tw/api/v25/occurrence?eventDate=2009-06-23&limit=20

● eventDate={YYYY-MM}

 

YYYY-MM

年月查詢

https://www.tbn.org.tw/api/v25/occurrence?eventDate=2009-06&limit=20

● eventDate={YYYY}

 

YYYY

年查詢

https://www.tbn.org.tw/api/v25/occurrence?eventDate=2009&limit=20

● eventDate={YYYY-MM-DD~YYYY-MM-DD}

 

YYYY-MM-DD~YYYY-MM-DD

年月日範圍

https://www.tbn.org.tw/api/v25/occurrence?eventDate=2009-06-01~2009-06-30&limit=20

● eventDate={YYYY-MM~YYYY-MM}

 

YYYY-MM~YYYY-MM

年月範圍

https://www.tbn.org.tw/api/v25/occurrence?eventDate=2009-05~2009-07&limit=20

● eventDate={YYYY~YYYY}

 

YYYY~YYYY

年範圍

https://www.tbn.org.tw/api/v25/occurrence?eventDate=2009~2010&limit=20

year

觀測日期:年

數字

正整數,完整西元年,如1968。本參數為eventDate為年份查詢之變形。支援範圍查詢

https://www.tbn.org.tw/api/v25/occurrence?year=2009&limit=20

month

觀測日期:月

數字

正整數,1-12

https://www.tbn.org.tw/api/v25/occurrence?month=6&limit=20

eventPlaceAdminarea

行政區名

文字

支援部分查詢

https://www.tbn.org.tw/api/v25/occurrence?eventPlaceAdminarea=南投&limit=20

boundedBy

四界

文字

採用Well-known text (WKT)格式:“最大經度,最大緯度 最小經度,最小緯度”,如121.06 24.11,120.02 23.36

https://www.tbn.org.tw/api/v25/occurrence?boundedBy=121.06 24.11,120.02 23.36&limit=20

polygon

多邊形座標

文字

請見底下polygon參數格式,採用Well-known text (WKT)格式

https://www.tbn.org.tw/api/v2/occurrence?polygon=121.29 24.81,121.69 24.83,121.71 24.42,121.01 24.56,121.29 24.81&limit=20

circle

中心點座標+半徑

文字

中心點座標採用Well-known text (WKT)格式。半徑單位為公里,半徑範圍最小為1,最大為50,只接受整數。

如:中心點為120.92 23.65,搜尋半徑13公里,寫為circle=120.92 23.65,13

https://www.tbn.org.tw/api/v25/occurrence?circle=120.92 23.65,13&limit=20

gridID

TBN網格編號

文字

網格編號有4種尺度:    
    100x100km網格:2720    
    10x10km網格:2720-61    
    5x5km網格:2720-61-01    
    1x1km網格:2720-61-01-21    
網格編號方法請見「TWGrid-WGS84 台灣經緯網格系統

https://www.tbn.org.tw/api/v25/occurrence?gridID=2720&limit=20    
 

selfProduced

是否為生多所自產資料

布林值

是否為農業部生物多樣性研究所的研究資料管理中心(RA)發佈的觀測紀錄。 是=y,否=n

https://www.tbn.org.tw/api/v25/occurrence?selfProduced=y&limit=20

 

polygon 參數格式

類型

code

範例網址

121.29 24.81,121.69 24.83,121.71 24.42,121.01 24.56,121.29 24.81 或    
(((121.29 24.81,121.69 24.83,121.71 24.42,121.01 24.56,121.29 24.81)))

https://www.tbn.org.tw/api/v25/occurrence?polygon=(((121.29 24.81,121.69 24.83,121.71 24.42,121.01 24.56,121.29 24.81)))&limit=20

By Mwtoews - Own work, CC BY-SA 3.0

(((121.59 24.22,121.60 24.22,121.35 23.50,120.40 23.68,121.59 24.22) => 外圈     
,(120.75 23.83,120.82 23.87,120.82 23.79,120.72 23.80,120.75 23.83)))=> 內圈

https://www.tbn.org.tw/api/v25/occurrence?polygon=(((121.59 24.22,121.60 24.22,121.35 23.50,120.40 23.68,121.59 24.22),(120.75 23.83,120.82 23.87,120.82 23.79,120.72 23.80,120.75 23.83)))&limit=20

(((121.29 24.81,121.69 24.83,121.71 24.42,121.01 24.56,121.29 24.81)),((120.75 23.83,120.82 23.87,120.82 23.79,120.72 23.80,120.75 23.83)))

https://www.tbn.org.tw/api/v25/occurrence?polygon=(((121.29 24.81,121.69 24.83,121.71 24.42,121.01 24.56,121.29 24.81)),((120.75 23.83,120.82 23.87,120.82 23.79,120.72 23.80,120.75 23.83)))&limit=20

(((121.29 24.81,121.69 24.83,121.71 24.42,121.01 24.56,121.29 24.81)) => polygon1(no hole)    
,((121.59 24.22,121.60 24.22,121.35 23.50,120.40 23.68,121.59 24.22),(120.75 23.83,120.82 23.87,120.82 23.79,120.72 23.80,120.75 23.83))) => polygon2 (with hole)

https://www.tbn.org.tw/api/v25/occurrence?polygon=(((121.29 24.81,121.69 24.83,121.71 24.42,121.01 24.56,121.29 24.81)),((121.59 24.22,121.60 24.22,121.35 23.50,120.40 23.68,121.59 24.22),(120.75 23.83,120.82 23.87,120.82 23.79,120.72 23.80,120.75 23.83)))&limit=20

上表圖片皆使用 By Mwtoews - Own work, CC BY-SA 3.0

複合查詢

各查詢參數均可做聯集查詢。如以下網址查詢「TBN-DP 台灣維管束植物調查及物候觀察」資料集中「大花咸豐草」的觀測紀錄:

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

回傳範例:

{
    "meta": {
        "status": "SUCCESS",
        "total": 1114,
        "itemsCount": 20,
        "generateDate": "2023-09-17T10:33:35+08:00",
    },
    "links": {
        "self": "https://www.tbn.org.tw/api/v25/occurrence?taxonUUID=9164c378-ef51-4423-a166-1a979c73a97d&datasetUUID=248d6799-bb66-40a5-b7ba-b45bbb818ddc&limit=20",
        "next": "https://www.tbn.org.tw/api/v25/occurrence?taxonuuid=9164c378-ef51-4423-a166-1a979c73a97d&datasetuuid=248d6799-bb66-40a5-b7ba-b45bbb818ddc&limit=20&minID=42313959",
    },
    "data": [
        {
            "occurrenceID": "4d65d374-4c15-4d47-800d-6f5bc4c5f77b",
            "created": "2022-03-21 12:20",
            "modified": "2022-08-14 01:49",
            "recordNumber": null,
            "catalogNumber": null,
            "externalID": "tbn.dp.plant.4d65d374-4c15-4d47-800d-6f5bc4c5f77b",
            "decimalLatitude": "23.47",
            "decimalLongitude": "120.58",
            "coordinateUncertaintyInMeters": "30",
            "minimumElevationInMeters": null,
            "geodeticDatum": "WGS84",
            "coordinatePrecision": null,
            "gridID": "2820-15-11-13",
            "adminareaCode": "10010140",
            "county": "嘉義縣",
            "municipality": "竹崎鄉",
            "year": 2020,
            "month": 12,
            "day": 23,
            "hour": 12,
            "minute": 0,
            "taxonUUID": "9164c378-ef51-4423-a166-1a979c73a97d",
            "originalVernacularName": null,
            "protectedStatusTW": null,
            "categoryIUCN": null,
            "categoryRedlistTW": "不適用",
            "endemism": "非臺灣特有",
            "nativeness": "外來歸化 Naturalized (non-native)",
            "taxonRank": "種下階層",
            "taxonGroup": "被子植物",
            "scientificName": "Bidens pilosa var. radiata (Sch.Bip.) Sherff",
            "simplifiedScientificName": "Bidens pilosa radiata",
            "vernacularName": "大花咸豐草",
            "scientificNameID": null,
            "taiCOLNameCode": null,
            "tfNameCode": "C303120303050402050559011001500003003",
            "familyScientificName": "Asteraceae",
            "familyVernacularName": "菊科",
            "datasetUUID": "248d6799-bb66-40a5-b7ba-b45bbb818ddc",
            "datasetName": "TBN-DP 臺灣維管束植物調查及物候觀察",
            "datasetURL": "https://www.tbn.org.tw/dataset/248d6799-bb66-40a5-b7ba-b45bbb818ddc",
            "datasetAuthor": "沈明雅、張慧玲、倪旻萱、郭貴嵐、俞佑錚",
            "datasetPublisher": "農業部生物多樣性研究所",
            "resourceCitationIdentifier": "https://www.tbn.org.tw/dataset/248d6799-bb66-40a5-b7ba-b45bbb818ddc",
            "resourceContacts": "沈明雅、張慧玲、倪旻萱、郭貴嵐、俞佑錚",
            "basisOfRecord": "出現紀錄",
            "establishmentMeans": "野生",
            "individualCount": null,
            "organismQuantity": "常見common",
            "organismQuantityType": null,
            "recordedBy": "顏翎(綠保)",
            "partner": null,
            "identificationVerificationStatus": "已鑑定",
            "identifiedBy": "mia",
            "dataSensitiveCategory": null,
            "eventID": null,
            "samplingProtocol": null,
            "associatedMedia": "https://www.tbn.org.tw/sites/ozop/files/occurrence/media/4d/4c/file-2054572-97togkbn.jpeg",
            "mediaLicense": "CC BY",
            "license": "CC BY",
            "source": "https://plant.tbn.org.tw/occurrence/4d65d374-4c15-4d47-800d-6f5bc4c5f77b",
            "selfProduced": true,
            "dataGeneralizations": false,
            "sensitiveCategory": "無",
            "collectionID": null,
            "verbatimEventDate": null,
            "eventDate": "2020-12-23 12",
            "eventTime": "12",
            "eventPlaceAdminarea": "嘉義縣竹崎鄉",
            "countyCode": "10010"
        },
        ...
    ]
}

資料欄位

JSON欄位名

  • 欄位名 (JSON field name) 均為羅馬字英文字母,大小寫不同,範圍為[a-zA-Z]。
  • 欄位名命名採首字小寫駝峰式 (Camel) 命名法。

資料型態與允許值

  • 時間:字串,格式為西元10碼+24小時制精度至分之5碼格式,即YYYY-MM-DD HH:MM,台灣時區
  • UUID:字串,RFC 4122,需含斷字符號共36個字元
  • 數字
  • 文字
  • 列舉:為規定值之一
  • 布林:為True或False
  • 允許多值時,多值以半形分號;分隔
  • 無資料時回傳null

回傳欄位表

API欄位名

中文欄位名

型態

值與說明

occurrenceID

紀錄識別號

UUID

TBN觀測紀錄UUID

created

收錄時間

時間

v2.5.1新增TBN收錄本記錄時間,非原始資料集建立時間

modified

最後修改時間

時間

TBN最後修改時間,非原始資料集最後修改時間

recordNumber

自訂記錄編號

文字

 

catalogNumber

館號

文字

v2.5.1新增

externalID

外部識別碼

文字

外部資料匯入的原始ID

decimalLatitude

緯度(十進位)

數字

小數

decimalLongitude

經度(十進位)

數字

小數

coordinateUncertaintyInMeters

原始座標誤差(公尺)

數字

正整數

minimumElevationInMeters

最低海拔

數字

v2.5.1新增正整數+0

geodeticDatum

大地基準

文字

意旨decimalLatitude以及decimalLongitude的座標系統。為固定值:WGS84

coordinatePrecision

敏感資料模糊化程度

數字

小數

gridID

網格編號

文字

v2.5.1新增

adminareaCode

行政區代碼

文字

v2.5.1新增請見戶役政資訊系統資料代碼內容清單:省市縣市鄉鎮市區代碼

county

縣市

文字

 

municipality

鄉鎮區

文字

v2.5.1新增

year

觀測年

數字

整數

month

觀測月

數字

正整數

day

觀測日

數字

正整數

hour

觀測時

數字

正整數, 0

minute

觀測分

數字

正整數, 0

taxonUUID

物種UUID

UUID

TBN分類群UUID

originalVernacularName

原始紀錄物種

文字

原始資料所記錄之物種名

protectedStatusTW

保育類等級

列舉

[第一級、瀕臨絕種保育類野生動物, 第二級、珍貴稀有保育類野生動物, 第三級、其他應予保育之野生動物, 文化資產保存法:珍貴稀有植物]

categoryIUCN

國際紅皮書

列舉

附表-4:國際紅皮書表

categoryRedlistTW

國內紅皮書

列舉

附表-3:國內紅皮書表

endemism

臺灣特有

列舉

[台灣特有]

nativeness

原生性

列舉

[原生 Native, 外來 Non-native, 外來歸化 Naturalized (non-native), 外來栽培 Cultivated (non-native),境外 Overseas]

taxonRank

分類階層

列舉

附表-2:分類階層表

taxonGroup

類群

列舉

附表-1:類群表

scientificName

分類群學名

文字

含學名HTML格式資訊

simplifiedScientificName

簡學名

文字

純文字,不含HTML格式資訊

vernacularName

分類群俗名

文字

 

scientificNameID

分類群學名代碼

文字

即TaiCOL編碼

taiCOlNameCode

TaiCOL編碼

文字

v2.5.1更名,O改為大寫TaiCOL臺灣物種名錄編碼

tfNameCode

taxonfileCladeID

文字

植物學名編輯系統(TaxonFile)學名代碼(未開放)

familyScientificName

科 學名

文字

v2.5.1新增

familyVernacularName

科 俗名

文字

v2.5.1新增

datasetUUID

資料集UUID

UUID

TBN資料集UUID

datasetName

所屬資料集

文字

資料集名稱

datasetURL

資料集網址

文字

URL

datasetAuthor

資料集作者

文字

 

datasetPublisher

資料集發布者

文字

 

resourceCitationIdentifier

資料集連結URL

文字

 

resourceContacts

資料集聯絡人

文字

 

basisOfRecord

紀錄類型

列舉

[保存標本, 化石標本, 活體標本, 人為觀測, 機器觀測, 組織樣本, 出現紀錄]

establishmentMeans

類群當地原生性

列舉

[野生, 圈養/栽植, 不確定]

individualCount

個體數量

數字

正整數

organismQuantity

數量

文字

 

organismQuantityType

數量單位

文字

 

recordedBy

記錄者

文字

 

partner

紀錄參與者

文字

 

identificationVerificationStatus

鑑定狀態

列舉

[未鑑定, 已鑑定, 無法鑑定]

identifiedBy

鑑定者

文字

 

dataSensitiveCategory

紀錄敏感資料標示

列舉

v2.5.1新增[無, 輕度, 重度, 縣市, 座標不開放, 物種不開放]

eventID

調查活動編號

文字

原始資料所紀錄之調查活動編號

samplingProtocol

調查方法

文字

調查方法

associatedMedia

多媒體連結

文字

URL,可多值

mediaLicense

多媒體授權

列舉

[CC0, CC BY, CC BY-NC, OGDL-Taiwan-1.0]

license

觀測紀錄授權

列舉

[CC0, CC BY, CC BY-NC, OGDL-Taiwan-1.0]

source

觀測紀錄來源

文字

v2.5.1新增

selfProduced

selfProduced

布林

是否為TBN所屬機關生多所內部資料集。

dataGeneralizations

是否為敏感資料

布林

sensitiveCategory 無=False,其他=True

sensitiveCategory

敏感資料標示

列舉

[無, 輕度, 重度, 縣市, 座標不開放, 物種不開放]

collectionID

館號

文字

預計於v2.6移除博物館憑證號voucher

verbatimEventDate

描述性觀測時間

文字

預計於v2.6移除

eventDate

觀測日期

文字

預計於v2.6移除YYYY, YYYY-MM, YYYY-MM-DD, YYYY-MM-DD HH,或 YYYY-MM-DD HH:II

eventTime

調查活動時間

文字

預計於v2.6移除HH,HH:II

eventPlaceAdminarea

行政區

文字

預計於v2.6移除

countyCode

縣市代碼

文字

預計於v2.6移除請見戶役政資訊系統資料代碼內容清單:縣市代碼

 

附表-1:類群表

兩棲類

哺乳類

爬蟲類

魚類

鳥類

蜘蛛類

蜻蛉類

蝦蟹類

蝸牛與貝類

蛾類

蝶類

甲蟲類

其他昆蟲

其他無脊椎

原藻類

真菌類

石松類

苔蘚

蕨類

被子植物

裸子植物

 

附表-2:分類階層表

總域

亞域

總界

亞界

總門

亞門

總綱

亞綱

總目

亞目

總科

亞科

亞屬

種下階層

附表-3:國內紅皮書表

絕滅(EX, Extinct)

野外絕滅(EW, Extinct in the Wild)

區域滅絕(RE, Regionally Extinct)

極危(CR, Critically Endangered)

瀕危(EN, Endangered)

易危(VU, Vulnerable)

接近受脅(NT, Near Threatened)

暫無危機(LC, Least Concern)

資料缺乏(DD, Data Deficient)

不適用

未評估(NE, Not Evaluated)

附表-4:國際紅皮書表

絕滅(EX, Extinct)

野外絕滅(EW, Extinct in the Wild)

區域滅絕(RE, Regionally Extinct)

極危(CR, Critically Endangered)

瀕危(EN, Endangered)

易危(VU, Vulnerable)

接近受脅(NT, Near Threatened)

暫無危機(LC, Least Concern)

資料缺乏(DD, Data Deficient)

未評估(NE, Not Evaluated)