# 利用TaiCOL API服務在EXCEL中利用中文名讀取學名和taxon_id之資料

###### tags: `Excel VBA` `TaiCOL API`

臺灣物種名錄TaiCOL 於今年 (2023/3/31) 正式更新至新網站 https://taiCOL.tw/
(但整體使用起來，還是taibnet.sinica.edu.tw比較習慣.. XD 要慢慢適應)

不過，總而言之，在核對學名部分還是應該要去新的網站比對。
在API的服務上，也從原本的TaiCoL API version 1.1 更新為 version 2

#舊版ver 1.1 請見 https://taibnet.sinica.edu.tw/chi/taicol_api.php? 說明 (可能於今年年底結束服務)
#新版ver 2 請見 https://taicol.tw/api 說明

---
### 為什麼要用API服務?

有時候拿到的物種清單或是的時候，可能是中文名或學名都有可能，
因此很希望在Excel中建檔的時候，可以直接對應TaiCOL查詢的結果。

過去曾經直接下載物種名錄，再配合vlookup公式參照使用，
但如果名錄龐大，資料繁多，最後可能就造成Excel在讀取的時候緩慢，效能不好時還可能導致當掉...

因此，使用API服務回傳物種資料也是一個不錯的方式。
(只是不可能盡善盡美，有時候還是得自己判斷修正一下)

---
### 進入正題

在VBA上，我們需要先準備好下列東西
1. 導入VBA中所需使用的 VBA-JSON - JsonConverter
a.至https://github.com/VBA-tools/VBA-JSON 下載 VBA-Json
(我這邊下載的版本是VBA-JSON v2.3.1)
b.在VBA>插入(I)>檔案 中，選取 VBA-Json資料夾內的JsonConverter.bas檔案
成功後如下圖所示(就可以看到一個名為JsonConverter的模組)

2. 引用 Microsofit WinHTTP Services, version 5.1 和 Microsofit Scripting Runtime
說明: 於 工具>設定引用項目 勾選上述兩個項目....如下圖所示:

開始編寫程式碼

Sub GetNameFromTaiCOL()
    Dim commonName As String
    Dim scientificName As String
    Dim idCode As String
    Dim apiUrl As String
    Dim xhr As New WinHttpRequest
    Dim json As Object

    '設定選取範圍，針對選取範圍內的儲存格作業'   
    Selection.Select
    Dim Rng As Range
    For Each Rng In Selection
        For Each cell In Rng
    
        '取得儲存格內的名稱'
        commonName = cell.Value

          
       '取得對應名稱的API服務位置'
        apiUrl = "https://api.taicol.tw/v2/nameMatch?name=" & commonName
    
        '請求回送'
        xhr.Open "GET", apiUrl
        xhr.Send     
    
        '解析數據'
        Set json = JsonConverter.ParseJson(xhr.ResponseText)
        
        Dim datas As Collection
        Set datas = json("data")
    
        Dim data As Dictionary
        For Each data In datas
            '可在即時資訊視窗顯示回傳結果，此行可省略也沒關係'
            Debug.Print data("matched_name"), data("taxon_id")
            '在查詢儲存格旁的右1欄位回傳核對學名,右2欄位回傳對應taxon_id'
            scientificName = data("matched_name")
            idCode = data("taxon_id")
            cell.Offset(0, 1).Value = scientificName
            cell.Offset(0, 2).Value = idCode
        Next data
    Next
Next
End Sub

就成功啦~

---

### 這邊有點重要的說明：
:::info
**TaiCOL中的taxon_id是跟著物種，name_id是跟著學名**
* 假設目前有一個生物"甲"，牠初始會被鑑定一個學名(假設是Aaa hahahe好了)，並上傳至資料庫上建檔，那麼牠會得到一個**taxon_id** (ex: t000001) 和一個**name_id** (ex: 12345)。
* 但之後另一個學者認為"甲"應該是另一個種類(例如Aaa rulala)，那麼牠的**taxon_id**不會改變 (ex: 還是t000001) ，但是因為學名變了，所以**name_id**會改變 (ex: 12346)。
* 這就是所謂taxon_id跟著物種，name_id更著學名的狀態。

但因為TaiCOL上面的學名或物種鑑定，可能跟每一個單位或實驗室內，所認定的還有些出入。
不見得會接受TaiCOL上面的鑑定資訊建議，因此我們寫的物種中文名可能要找的就是原本直接對應的學名，而不是TaiCOL上進一步認為的有效學名。所以同時保留name_id和taxon_id是有必要的。對後續追蹤核對會比較有利。
而在無脊椎動物上，有時候我們還會去核對一下WoRMS資料庫學名的對應情況，再去選擇最終我們名錄所採用的學名。(WoRMS也有API服務，在他們的網頁中也有清楚的範例可參考)

(不過目前，我這邊選用的nameMatch服務當中，只提供taxon_id，尚未有回傳name_id的功能，可能要再透過其他的服務來回傳name_id，希望未來能夠在nameMatch中提供這個功能＞／／／＜）

以上。

by *Hsin-Ju*
*2023.04.21*
:::

---
推薦YT上的學習影片:
**Use Excel VBA to Read API Data**
by **Excel Macro Mastery**
https://www.youtube.com/watch?v=KZeYKZJzQIk&t=527s

感謝 TaiCOL 團隊解惑
感謝 timhall 於 github 釋出的 VBA-JSON v2.3.1