【新手上路(四)】TEJ REST API 使用手冊

官方說明文件之簡易版導讀

前言

TEJ官方本身有為Python、R的使用者開發專屬的套件，以便使用API來撈取資料。(Python api的說明文件)而為了讓其他程式的編程者，同樣能透過API來撈取資料，官網上也有REST API的說明文件。

REST API 的使用原理類似於網路爬蟲，是透過get一串網址來連接TEJ的資料庫。本篇將會以白話文的形式帶領大家了解REST API 的使用方式 💪💪

本文重點概要

• 🌟 API KEY申請/購買
• 🌟 使用說明
• 🌟 進階參數設定

🚪本次使用的相關網站連結🚪

• 1️⃣ API官方網站：TEJ API 官網
• 2️⃣本文範例產品包：TEJ E SHOP
• 3️⃣本文完整程式：TEJ GITHUB

* API KEY申請/購買

在正式使用我們API之前，如果尚未有API KEY，可以透過連結當中的申請試用或是EShop當中的產品包進行獲得，如下圖：

申請試用API KEY流程

TEJ E-Shop 介面

* 使用說明 📗

1️⃣ 匯入套件

import requests
import pandas as pd
import json

2️⃣ 輸入api_key

# 輸入 api_key
api_key = 'your key'
url = 'https://api.tej.com.tw/api/datatables/TWN/APRCD.json?api_key='+api_key

3️⃣ Get 網址的資訊

rq = requests.get(url)
rq.content

網址的資訊

4️⃣ 資料整理 (json ➡️ Dataframe)

經過整理後的資料是不是變得整齊多了阿 😎😎~

data = json.loads(rq.content)['datatable']['data']
columns = pd.DataFrame(json.loads(rq.content)['datatable']['columns'])['cname'].to_list()
stock_price = pd.DataFrame(data,columns=columns)
stock_price

Dataframe

* 進階參數設定 📚

進一步解析我們剛剛撈取的網址可以發現，網址的組成架構是有脈絡可循的!網址前面的部分是指定連結到TEJ API的資料庫，後面粗體字的部分則開始根據我們指定的資料庫名稱、資料表名稱、輸出格式和自定義的一些條件，進行連接。

TWN：台灣地區的資料庫。
APRCD：股價資料表。
json：資料輸出格式。
api_key：鑰匙(可以想成是登入FB、google時需要的密碼)。

https://api.tej.com.tw/api/datatables/{datatable_code}/{table_code}.{format}?<row_filter_criteria>
https://api.tej.com.tw/api/datatables/TWN/APRCD.json?api_key=<YOURAPIKEY> 

1️⃣ 撈取特定公司之股價

⚠️ 出現兩個參數以上都要在參數前面加 &，如&coid和&api_key⚠️

🔽 個股 🔽

以台灣加權指數(代號:Y9999)為例。

coid = 'Y9999'
url = 'https://api.tej.com.tw/api/datatables/TWN/APRCD.json?'+'&coid='+coid+'&api_key='+api_key
rq = requests.get(url)
data = json.loads(rq.content)['datatable']['data']
columns = pd.DataFrame(json.loads(rq.content)['datatable']['columns'])['cname'].to_list()
stock_price = pd.DataFrame(data,columns=columns)
stock_price

資料展示

🔽 多股 🔽

以台灣加權指數(代號:Y9999)、台積電(代號:2330)、聯發科(代號:2454)、陽明(代號:2609)為例。

coid = 'Y9999,2330,2454,2609'
url = 'https://api.tej.com.tw/api/datatables/TWN/APRCD.json?'+'&coid='+coid+'&api_key='+api_key
rq = requests.get(url)
data = json.loads(rq.content)['datatable']['data']
columns = pd.DataFrame(json.loads(rq.content)['datatable']['columns'])['cname'].to_list()
stock_price = pd.DataFrame(data,columns=columns)
stock_price

資料展示

👺 魔鬼藏在細節裡 👺

在多股的範例中，宣告 coid 為四檔股票代碼所組成的字串，若以個股的資料筆數(5,300)來推算，四檔個股至少會有20,000筆以上的資料，為何只有抓到10,000筆資料?

TEJ為維持主機運行的穩定，單次取得資料限制最多10,000筆，而我們可以透過擷取 next_cursor_id 的資訊，並用參數opts.cursor_id = next_cursor_id 來取得後面的資料。

💻 next_cursor_id 💻

rq.json()['meta']['next_cursor_id']

擷取 next_cursor_id 的資訊

依照上面的邏輯，當資料有30,000筆時，就會有3個 next_cursor_id，也就是每10,000筆資料就會有一個 next_cursor_id，這時就輪到 while 迴圈出場了 ❗️

💻 解決多個next_cursor_id 💻

小編這邊已經幫各位整理好了，只要先運行下面的函數，再運行下方的程式碼，就可以輕鬆的一次撈取多股 😎😎

# 多股
coid = 'Y9999,2330,2454,2609'
stock_price = tej_get_data(
                    db_code='TWN/APRCD',
                    api_key=api_key,
                    coid = coid)
stock_price

資料展示

2️⃣ 欄位篩選

以台灣加權指數(代號:Y9999)為例。

🔽 單一欄位 🔽

新增參數&opts.columns=open_d，指定columns 為開盤價

# 單一欄位
coid = 'Y9999'
url = 'https://api.tej.com.tw/api/datatables/TWN/APRCD.json?&opts.columns=open_d'+'&api_key='+api_key+'&coid='+coid
rq = requests.get(url)
data = rq.json()['datatable']['data']
columns = pd.DataFrame(rq.json()['datatable']['columns'])['cname'].to_list()
stock_price = pd.DataFrame(data,columns=columns)
stock_price

資料展示

🔽 多欄位 🔽

欄位：股票代碼、日期、開盤價、最高價、最低價、收盤價。

# 多欄位
coid = 'Y9999'
columns = 'coid,mdate,open_d,high_d,low_d,close_d'
url = 'https://api.tej.com.tw/api/datatables/TWN/APRCD.json?'+'&opts.columns='+columns+'&api_key='+api_key+'&coid='+coid
rq = requests.get(url)
data = rq.json()['datatable']['data']
columns = pd.DataFrame(rq.json()['datatable']['columns'])['cname'].to_list()
stock_price = pd.DataFrame(data,columns=columns)
stock_price

資料展示

3️⃣ 日期篩選

以台灣加權指數(代號:Y9999)為例。

起始日期設定為 2020–01–01(start)，結束日期為 2020–12–31(end)。

參數設定：

• mdate.gte= start： 日期>=2020–01–01
• mdate.lte = end： 日期<=2020–12–31

# 日期篩選
coid = 'Y9999'
start = '2020-01-01'
end = '2020-12-31'
url = 'https://api.tej.com.tw/api/datatables/TWN/APRCD.json?'+'&mdate.gte='+start+'&mdate.lte='+end+'&api_key='+api_key+'&coid='+coid
rq = requests.get(url)
data = rq.json()['datatable']['data']
columns = pd.DataFrame(rq.json()['datatable']['columns'])['cname'].to_list()
stock_price = pd.DataFrame(data,columns=columns)
stock_price

資料展示

4️⃣ 表格資訊查詢

以上市(櫃)未調整股價(日)(TWN/APRCD)為例，運行下方的程式碼便可獲得欄位代號及中文欄位名稱等資訊。

datatable_code = 'TWN/APRCD'
url = 'https://api.tej.com.tw/api/datatables/'+datatable_code+'/metadata?api_key='+api_key
rq = requests.get(url)
rq.json()

資料展示

5️⃣ 搜尋功能

搜尋每股盈餘，會出現相當多變數，可參考TEJ API 官網

matchType 匹配類別

• TABLE_MATCH:關鍵字在表格名稱或說明中
• COLUMN_MATCH:關鍵字在欄位名稱或說明中
• TABLE_MATCH & COLUMN_MATCH:關鍵字在表格及欄位名稱或說明中

key_word = '每股盈餘'
url = 'https://api.tej.com.tw/api/search/table/'+key_word+'?api_key='+api_key
rq = requests.get(url)
rq.json()

資料展示

6️⃣ API KEY 權限查詢

api_key = 'your key'
url = 'https://api.tej.com.tw/api/apiKeyInfo/'+api_key
rq = requests.get(url)
rq.json()

權限查詢

結語

今天的內容是讓大家對於我們TEJ Rest API有深入的認知以及了解，透過實際的程式碼執行可以了解TEJ Rest API的使用邏輯之外，也可以讓大家透過這些功能對TEJ龐大的資料庫進行更為便捷的撈取噢~

* 再次附上相關網站連結 💪

• API官方網站：TEJ API 官網
• 本文範例產品包：TEJ E SHOP
• 本文完整程式：TEJ GITHUB

🌟有任何使用上的問題都歡迎與我們聯繫：聯絡資訊🌟

附上完整程式碼 🚪