公共運輸 on IT 空間

「TDX 運輸資料流通服務平台」Google Apps Script 範例，PTX 平台的升級版~

jia@jiatool.com (Jia) — Fri, 30 Dec 2022 21:00:00 +0800

前言

先預祝 2023 元旦快樂~🎉🎉🎉 恭喜各位又老一歲了(?

之前介紹的「 PTX 公共運輸資訊平台」已經確定在今年 2022/12/01 正式落日，所以後來我有寫一篇將取代 PTX 平台的「TDX 運輸資訊整合流通服務平台」介紹，並示範如何使用 Python 來串接。

PTX 平台關閉

因為剛好有網友詢問，所以本篇也會使用 Google Apps Script 來取得 TDX 的交通資料，兩者在 API 認證授權機制差異不小。
關於 TDX 平台的介紹、如何註冊並取得API金鑰等資訊之前這篇文章都講解過了，這篇我們就直接進入 Google Apps Script 程式主題。

TDX 運輸資訊整合流通服務平台

取得API金鑰

TDX 平臺現階段開放每位會員最多建立三把API金鑰，每把API金鑰由一組 Client Id 和 Client Secret 所組成。

每個呼叫來源端 IP 呼叫次數限制為 50 次/秒。

TDX 平臺 API 採 OIDC Client Credential 機制進行身分驗證，程式介接範例可參考範例程式碼。

登入 TDX 平台後，前往會員中心 > (左邊) > 資料服務 > API金鑰頁面，點擊 "編輯" 即可查看 "Client Id" 和 "Client Secret"，將這兩組字串記錄下來，call API 時需要帶上。

API金鑰頁面

有關 API 金鑰服務使用流程說明，請參考官方說明。

API 認證授權機制

詳細步驟說明如下:

取得 Access Token

依照以下格式發出請求：

Request URL: https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token
Request Method: POST
Request Headers:
content-type: application/x-www-form-urlencoded
data:
grant_type: client_credentials
client_id: <your_client_id>
client_secret: <your_client_secret>

data 參數說明如下:

Key	Value
`grant_type`	固定使用 `client_credentials`
`client_id`	您的 Client Id，從 TDX 會員中心取得
`client_secret`	您的 Client Secret，從 TDX 會員中心取得

回傳資料是 JSON 格式，其中包含 access_token 參數，就是我們要的 Access Token。

對應的 Google Apps Script code：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


function GetAuthorizationToken() {
var token_url = "https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token";
var options = {
"method": "post",
"headers": {
"content-type": "application/x-www-form-urlencoded"
},
"payload": {
"grant_type": "client_credentials",
"client_id": '<YOUR CLIENT ID>',
"client_secret": '<YOUR CLIENT SECRET>'
}
};
var response = UrlFetchApp.fetch(token_url, options);
outData = JSON.parse(response.getContentText());
// console.log(outData);
 return outData['access_token'];
}

呼叫 TDX API 服務，取得數據資料

Request URL: TDX_API_URI
Request Method: GET
Request Headers:
authorization: Bearer <Access_Token>

* 若 Access Token 時間超過有效期限(第一步驟收到回應中的 expires_in 參數)，則再重新透過第一步驟取得即可。

對應的 Google Apps Script code：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


function doGet(e) {
var url = 'https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON'
var options = {
"method": "get",
"headers": { "authorization": "Bearer " + GetAuthorizationToken() }
};
var response = UrlFetchApp.fetch(url, options);
// console.log(response.getResponseCode());
 var outData = JSON.parse(response.getContentText());
console.log(outData);
return ContentService.createTextOutput(JSON.stringify(outData)).setMimeType(ContentService.MimeType.JSON);
}

* 官方的說明文件： https://github.com/tdxmotc/SampleCode

完整 Google Apps Script 程式範例

以同樣條件當範例查詢：台鐵"台北"車站即時的列車到離站看板資訊，並且只要"逆行"的列車

查詢的 URL 會長得像這樣：
https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


var CLIENT_ID = '<YOUR CLIENT ID>';
var CLIENT_SECRET = '<YOUR CLIENT SECRET>';
function doGet(e) {
var url = 'https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON'
var options = {
"method": "get",
"headers": { "authorization": "Bearer " + GetAuthorizationToken() }
};
var response = UrlFetchApp.fetch(url, options);
// console.log(response.getResponseCode());
 var outData = JSON.parse(response.getContentText());
console.log(outData);
return ContentService.createTextOutput(JSON.stringify(outData)).setMimeType(ContentService.MimeType.JSON);
}
function GetAuthorizationToken() {
var token_url = "https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token";
var options = {
"method": "post",
"headers": {
"content-type": "application/x-www-form-urlencoded"
},
"payload": {
"grant_type": "client_credentials",
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET
}
};
var response = UrlFetchApp.fetch(token_url, options);
outData = JSON.parse(response.getContentText());
// console.log(outData);
 return outData['access_token'];
}

透過上方的 "執行" 確認沒問題後，可參考這篇的教學將程式部署起來。

其他程式範例

除了參考我上面的 Google Apps Script 範例，與我上次整理的 Python 教學，TDX 官方有提供 C#、JavaScript、Java、PHP、R 程式語言的範例程式碼，需要的可前往參考 ( GitHub )。

結語

如果你想做的應用需要「公共運輸」相關資料，那應該就是串接 TDX 平台，資料齊全、方便很多~

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
TDX 運輸資料流通服務平台 | 官網
 TDX API 說明 | Swagger 文件工具
 TDX 官方介接說明與範例程式碼 | GitHub
TDX 平台常見問題 | 官網

與其埋怨暗路，不如自己點燈。

「TDX 運輸資料流通服務平台」含 Python 範例程式，PTX 平台的升級版~

jia@jiatool.com (Jia) — Sun, 19 Jun 2022 21:25:00 +0800

前言

在之前文章介紹 PTX 公共運輸整合資訊流通服務平台，它整合多項公共運輸的資料服務 API，供我們串接取得相關數據。

但經網友提醒，才發現 PTX 竟然只服務到今年(2022年)底，之後會改以「TDX 運輸資訊整合流通服務平台」代替，因此本篇文章將帶大家快速了解一下 TDX 平台，以及實際使用 Python 來串接，取得相關數據資料。

PTX 平台關閉

後來我有寫一篇 Google Apps Script 範例程式可以參考哦~

TDX 運輸資訊整合流通服務平台

TDX 平台說明

按照官網的說法，TDX 整合交通部運輸數據五大平台(PTX、Traffic、GIS-T、TICP、LINK)，並使用全新的認證授權方式管控資源存取權限，提供單一服務查詢與介接入口。短時間內五大平台與 TDX 平台將持續並行運作，但未來會以 TDX 為主要的數據流通平台。
(參考： TDX 平台常見問題 )

TDX 整合五大平台 (圖片來源：TDX官網)

實際使用其實「TDX 運輸資訊整合流通服務平台」服務及概念是跟「PTX 公共運輸整合資訊流通服務平台」差不多的，只是相較於 PTX 平台，TDX 平台又多了許多種類的資料，像是 "即時路況"、"停車資訊"、"GIS圖資"、"道路編碼" 等等也把它整合進來。

TDX 平台服務範疇

TDX 平台也有個詳細各項服務查詢頁面，可依照 "服務類型"、"資料主題"、"領域類型"、"資料類型" 來做篩選。

TDX 各項服務查詢

註冊會員 & 取得API金鑰

同樣為了系統資源使用之公平性與資通訊安全考量，要先註冊會員來取得 API 金鑰( TDX 註冊頁面 )，但不知道是不是因為平台還在試營運階段的關係，審核完成並沒有寄 Email 通知，是我主動登入平台才發覺已審核通過……

註冊 TDX 平台會員

登入 TDX 平台後，前往會員中心 > (左邊) > 資料服務 > API金鑰頁面，對預設的API Key (或建立新的金鑰) 點擊 "編輯"，即可查看 "Client Id" 和 "Client Secret"，這兩組字串先記錄下來，之後 call API 時需要帶上。

API金鑰頁面

API 呼叫次數限制：

使用 API 金鑰呼叫，每個呼叫來源端 IP 呼叫次數限制為 50 次/秒 (無每日上限)。
不使用 API 金鑰呼叫，則僅能透過瀏覽器呼叫 API，且每個呼叫來源端 IP 的上限為每日 50 次。

有關 API 金鑰服務使用流程說明，請參考官方說明。

Swagger 工具

從上方導航欄開發指引 > API說明，前往 TDX 平台的 Swagger 工具，能查看有提供哪些 API，與各自的請求參數與回傳欄位說明。
詳細使用說明可以查看之前我寫的 PTX 介紹 (含 Odata 說明) 文章。

TDX 平台 Swagger 工具

右方有 Authorize 按鈕，填入 "Client Id" 與 "Client Secret" 驗證，即可使用你的 API 金鑰來呼叫。不使用 API 金鑰呼叫，有每日 50 次的上限。

API 認證授權機制

API 認證授權機制與 PTX 平台有蠻大的差異，簡單來說每次請求前要先身份認證取得 Access Token，才能使用 Access Token 來取得 TDX API 服務的數據資料。
(或使用尚未過期的 Access Token，有效期限預設為 1 天)

詳細步驟說明如下:

取得 Access Token

依照以下格式發出請求：

Request URL: https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token
Request Method: POST
Request Headers:
content-type: application/x-www-form-urlencoded
data:
grant_type: client_credentials
client_id: <your_client_id>
client_secret: <your_client_secret>

data 參數說明如下:

Key	Value
`grant_type`	固定使用 `client_credentials`
`client_id`	您的 Client Id，從 TDX 會員中心取得
`client_secret`	您的 Client Secret，從 TDX 會員中心取得

回傳資料是 JSON 格式，其中包含 access_token 參數，就是我們要的 Access Token。

呼叫 TDX API 服務，取得數據資料

Request URL: TDX_API_URI
Request Method: GET
Request Headers:
authorization: Bearer <Access_Token>

* 若 Access Token 時間超過有效期限(第一步驟收到回應中的 expires_in 參數)，則再重新透過第一步驟取得即可。

* 官方的說明文件： https://github.com/tdxmotc/SampleCode

完整 Python 程式範例

因為 TDX 平台的 API 一樣使用 OData (Open Data Protocol) 標準介面，所以這邊我就不再寫一次了，還不太懂的可前往「PTX 平台」API 介紹 (含 Odata 說明) 了解。

同樣以下方條件當範例查詢：

台鐵"台北"車站即時的列車到離站看板資訊，並且只要"逆行"的列車

查詢的 URL 會長得像這樣：
https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON

會發現與 PTX 平台根本一樣，只差在網址前方的部分。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import requests
client_id = '<your_client_id>'
client_secret = '<your_client_secret>'
class TDX():
def __init__(self, client_id, client_secret):
self.client_id = client_id
self.client_secret = client_secret
def get_token(self):
token_url = 'https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token'
headers = {'content-type': 'application/x-www-form-urlencoded'}
data = {
'grant_type': 'client_credentials',
'client_id': self.client_id,
'client_secret': self.client_secret
}
response = requests.post(token_url, headers=headers, data=data)
# print(response.status_code)
# print(response.json())
return response.json()['access_token']
def get_response(self, url):
headers = {'authorization': f'Bearer {self.get_token()}'}
response = requests.get(url, headers=headers)
return response.json()
if __name__ == '__main__':
tdx = TDX(client_id, client_secret)
# url = 'https://tdx.transportdata.tw/api/basic/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON'
base_url = "https://tdx.transportdata.tw/api"
# 取得指定[車站]列車即時到離站電子看板(動態前後30分鐘的車次)
endpoint = "/basic/v2/Rail/TRA/LiveBoard/Station/1000"
filter = "Direction eq 1" # 順逆行: [0:'順行', 1:'逆行']
url = f"{base_url}{endpoint}?$filter={filter}&$format=JSON"
response = tdx.get_response(url)
print(response)

如此應該就能順利取得資料 🎉🎉🎉

其他程式範例

除了參考我上面的 Python 範例，TDX 官方有提供 JavaScript 與 C# 程式語言的範例程式碼，需要的可前往參考 ( GitHub )。

我有寫一篇 Google Apps Script 範例程式可以參考。

也感謝熱心網友 meebox，提供 "適用在嵌入式系統的 MicroPython 環境、token 有效期判斷" 的版本：
https://github.com/codemee/tdx

結語

這次快速(?)帶大家了解「TDX 運輸資料流通服務平台」，看起來就是 PTX 平台的升級版，加入更多不同服務的資料。
如果你之前已經用 PTX 做些作品出來，不妨試著將其改串接至 TDX，畢竟可能明年 PTX 平台就無法使用了。

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
TDX 運輸資料流通服務平台 | 官網
 TDX API 說明 | Swagger 文件工具
 TDX 官方介接說明與範例程式碼 | GitHub
TDX 平台常見問題 | 官網

你不可能有先見之明，只能有後見之明，
因此，你必須相信，這些小事一定會和你的未來產生關聯。

—— 史蒂夫·賈伯斯

「PTX 公共運輸資訊平台」Google Apps Script 範例程式

jia@jiatool.com (Jia) — Sat, 14 May 2022 20:45:00 +0800

因部內目前已收攏資料於TDX運輸資訊整合流通服務平台，本平台預計將於2022/12/1落日，屆時您的會員金鑰將於2022/12/1起停用。
為避免您短時間內需移轉之困擾，即日起本平台不再受理審核會員註冊。
建議您依據身分類型至TDX申請會員，非常感謝您的支持。

前言

在之前的兩篇文章裡，我們分別介紹 PTX 公共運輸整合資訊流通服務平台整合多項大眾運輸的資料、說明 OData（Open Data Protocol）格式如何使用，與實際使用 Python 來串接 PTX 平台。

本篇文章將帶你換成使用 Google Apps Script 來串接 PTX 平台，取得這些相關數據資料 💾，還可以做出自己的簡易 API。
(Google Apps Script 其實是基於 JavaScript 來的，所以基本的語法大致都相同。)

關於 PTX 平台我寫了三篇文章來介紹與程式教學：

「PTX 公共運輸資訊平台」API 介紹 (含 Odata 說明)
「PTX 公共運輸資訊平台」Python 範例
「PTX 公共運輸資訊平台」Google Apps Script 範例 <– 本篇

PTX 公共運輸整合資訊流通服務平台

後來發現 PTX 竟然只服務到今年(2022年)底，之後會改以 TDX 運輸資訊整合流通服務平台，因此又特別寫一篇文章帶大家快速了解一下 TDX 平台：
「TDX 運輸資料流通服務平臺」含 Python 範例程式，PTX 平台的升級版~

創建 Google Apps Script 專案

可能有些人沒接觸過 Google Apps Script，我這邊先說明兩種創建的方式：

第一種到 Apps Script 頁面創建專案，預設會儲存在你 Google 雲端硬碟的根目錄。

創建 Google Apps Script 專案 -1

第二種在 Google 雲端硬碟裡新增 Google Apps Script 檔案 (如果選單內沒看到，可以點擊 "連結更多應用程式" 去尋找&加入)。

創建 Google Apps Script 專案 -2

選擇一種你順手的方式創建專案即可，好了我們就開始吧 🚌

API 認證授權機制

一樣先撰寫放在 Header 裡的 HMAC 認證授權 🔓，關於目前 PTX 平台採用 HMAC 認證授權機制說明，可以參考上一篇文章。

參數如下：

Key	Value
`Authorization`	`hmac username="APP ID", algorithm="hmac-sha1", headers="x-date", signature="Base64(HMAC-SHA1("x-date: " + x-date , APP Key))"`
`x-date`	`Wed, 19 Apr 2017 08:37:50 GMT`

※ 建議於每次請求 API 服務當下建立新的 signature，簽章時效性為 5 分鐘。

如果 HMAC 認證有問題、未符合身份驗證，它會回覆下列訊息：

HTTP Status Code 403：
- (1) HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication （x-date 的間隔時間超過定義的 clock skew 秒數）
- (2) HMAC signature does not match （日期格式正確，但簽章演算法有問題）
HTTP Status Code 401：
- (1) Unauthorized （未帶簽章，未經授權）

依照上方說明，使用 Google Apps Script 語法把這個 HMAC 編碼撰寫出來：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


function GetAuthorizationHeader() {
var AppID = '<YOUR APP ID>';
var AppKey = '<YOUR APP KEY>';
var xdate = new Date().toGMTString();
//HMAC-SHA1 運算
 var signature = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_SHA_1, "x-date: " + xdate, AppKey);
//轉成Base64
 var HMAC = Utilities.base64Encode(signature);
var Authorization = 'hmac username=\"' + AppID + '\", algorithm=\"hmac-sha1\", headers=\"x-date\", signature=\"' + HMAC + '\"';
return { 'Authorization': Authorization, 'x-date': xdate ,'Accept-Encoding': 'gzip'};
}

Google Apps Script 程式範例

我們一樣使用上次的例子：

台鐵"台北"車站即時的列車到離站看板資訊，並且只要"逆行"的列車

先進到 PTX 平台的 Swagger 文件，找到 " 取得指定[車站]列車即時到離站電子看板 "：

列車即時到離站電子看板

填入 "台北車站" 代碼 1000 ( 車站代碼表 )，並依照下方 Responses 欄位說明 "Direction" 代表順逆行(0:'順行', 1:'逆行')，在 $filter 填入 Direction eq 1，指定 JSON 格式，最後點擊藍色 "Execute" 按鈕，看看回傳結果是不是我們想要的~

(關於這些 Odata 的寫法，我在第一篇文章有說明，忘記的可以回去看看)

它顯示的 "Request URL" 長得像這樣：
https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?%24filter=Direction%20eq%201&%24format=JSON

這是以下這句經過 URL 編碼後的結果：
(程式中 requests 會自動幫我們編碼，因此輸入底下這句也可以)
https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON

接下來將這些代入程式中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


function doGet() {
var response = UrlFetchApp.fetch(
"https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON",
{method: 'GET', 'headers': GetAuthorizationHeader()}
);
// console.log(response.getResponseCode());
 outData = JSON.parse(response.getContentText());
console.log(outData);
return ContentService.createTextOutput(JSON.stringify(outData)).setMimeType(ContentService.MimeType.JSON);
}

點擊上方的 "執行"，程式執行後會自動開啟 "執行記錄"，程式碼中 console.log(); 的部分會在此顯示出來。

如此即可順利取得資料 🎉🎉🎉

"執行" GAS 程式

完整 Google Apps Script 程式範例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


function doGet() {
var response = UrlFetchApp.fetch(
"https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON",
{method: 'GET', 'headers': GetAuthorizationHeader()}
);
// console.log(response.getResponseCode());
 outData = JSON.parse(response.getContentText());
console.log(outData);
return ContentService.createTextOutput(JSON.stringify(outData)).setMimeType(ContentService.MimeType.JSON);
}
function GetAuthorizationHeader() {
var AppID = '<YOUR APP ID>';
var AppKey = '<YOUR APP KEY>';
var xdate = new Date().toGMTString();
//HMAC-SHA1 運算
 var signature = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_SHA_1, "x-date: " + xdate, AppKey);
//轉成Base64
 var HMAC = Utilities.base64Encode(signature);
var Authorization = 'hmac username=\"' + AppID + '\", algorithm=\"hmac-sha1\", headers=\"x-date\", signature=\"' + HMAC + '\"';
return { 'Authorization': Authorization, 'x-date': xdate ,'Accept-Encoding': 'gzip'};
}

部署

Google Apps Script 特別的地方就在於可直接把程式部署起來，不需要另外找伺服器、線上服務來處理，非常方便。

像是上面範例的 function doGet()，就是 Google Apps Script 內定的函式，當我們發佈成 "網頁應用程式" 後，對網址發送 GET 請求(就是在瀏覽器上前往此網址)，就會執行此函式。
另外也有 function doPost() 對應 POST 請求。

如果想在網址後方帶入參數，像是這樣：
https://webdomain.com?stationId=1000

就使用這種寫法，即可取到對應參數後方的字串：
var stationId = e.parameter.stationId;

帶入參數

那我們開始來 "部署" 吧~

確認檔案存檔後(重要！！)，點擊右上角的 "部署" > "新增部署作業" 按鈕。

選擇 "部署" > "新增部署作業"

左邊齒輪形狀的設定打開，選擇 "網頁應用程式"。

選擇 "網頁應用程式"

"執行身分" 和 "誰可以存取" 可以自己看需求更改，執行 "部署"。

執行部署

用這邊產生的網址，到瀏覽器貼上，就可以取得剛剛的資料了~

網頁應用程式網址

* 如果有編輯，需要存檔後再 "部署" 一次，而且網址會更改。但舊版本還會存在，需要到 "管理部署作業" 將其封存。

部署成網頁

除了像上述的方法當成一支 API，也可以回傳 HTML，顯示成網頁喔~

左邊檔案新增一個 HTML。

新增 HTML 檔案

HTML 檔案內容撰寫完成後，在原先的程式碼 doGet() 中，回傳這個 HTML 檔案即可。
(index 是 HTML 的檔名)

回傳 HTML

1
2
3


function doGet() {
return HtmlService.createHtmlOutputFromFile('index');
}

因此你可以在 Google Apps Script 裡，取得 PTX 平台大眾運輸資料後，顯示到自製的網頁上，嘗試做一個🚅查詢時刻表的網頁服務吧~

其他程式範例

除了參考我上面的 Google Apps Script 範例，PTX 官方也提供不同程式語言的範例程式碼提供開發者下載 ( GitHub )。

平台提供
- ASP.NET
- Java
- JavaScript
網友提供
- Bourne Shell
- C# 與 .NET Standard 2.0
- Go
- Go Client SDK - Code generated by go-swagger
- Node.js
- python
- Ruby
- Swift
- PHP
- Postman

結語

有關更多 Google Apps Script 語法說明，歡迎參考 Google Apps Script 官方文件。

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
公共運輸整合資訊流通服務平台 | 官網
 PTX 資料服務使用注意事項 | GitHub
PTX 官方範例程式碼 | GitHub
Google Apps Script 官方文件

我不是神童，只是堅持打好每一顆球。

—— 林昀儒 (台灣桌球國手)

「PTX 公共運輸資訊平台」Python 範例程式

jia@jiatool.com (Jia) — Sat, 30 Apr 2022 20:55:00 +0800

前言

在上一篇文章中，我們介紹了 PTX 公共運輸整合資訊流通服務平台，它整合公車、臺鐵、高鐵、捷運等多項公共運輸的資料服務 API，以及說明 OData（Open Data Protocol）標準介面格式如何使用。

本篇文章將帶你實際使用 Python 來串接 PTX 平台，取得這些相關數據資料 💾。

關於 PTX 平台我寫了三篇文章來介紹與程式教學：

PTX 公共運輸整合資訊流通服務平台

API 認證授權機制

目前 PTX 平台採用 HMAC 認證授權機制，在送出請求時 headers 需代上規定的資料，它會依照 HTTP header 資訊來判別用戶是否有授權身份 🔓。

官方說明如下：

HMAC 機制：以 HMAC 簽章驗證使用者的身份，用戶在請求 API 服務時，將 APP Key 與當下時間(格式請使用GMT時間) 做 HMAC-SHA1 運算後轉成 Base64 格式，帶入 signature 屬性欄位，服務器端將驗證用戶請求時的 header 欄位，驗證使用者的身份及請求服務的時效性。

HMAC Signature 簽章時效性：於 MOTC Helper 該網頁測試時，請在最上方輸入 API Key 與 API ID (請再次確認是否有把 APP Key 跟 ID 填寫正確，若欄位資訊相反會無法執行)。點選 Explore ，每次請求下方 API 時，會於 header 帶入 Authorization 及 x-date ，依照請求當下的時間 & API Key 製作簽章。

參數如下：

Key	Value
`Authorization`	`hmac username="APP ID", algorithm="hmac-sha1", headers="x-date", signature="Base64(HMAC-SHA1("x-date: " + x-date , APP Key))"`
`x-date`	`Wed, 19 Apr 2017 08:37:50 GMT`

※ 建議於每次請求 API 服務當下建立新的 signature，簽章時效性為 5 分鐘。

如果 HMAC 認證有問題、未符合身份驗證，它會回覆下列訊息：

HTTP Status Code 403：
- (1) HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication （x-date 的間隔時間超過定義的 clock skew 秒數）
- (2) HMAC signature does not match （日期格式正確，但簽章演算法有問題）
HTTP Status Code 401：
- (1) Unauthorized （未帶簽章，未經授權）

依照上方說明，使用 Python 把這個 HMAC 編碼寫出來，這邊我也是參考範例來做修改的。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


class Auth():
def __init__(self, app_id, app_key):
self.app_id = app_id
self.app_key = app_key
def get_auth_header(self):
xdate = datetime.utcnow().strftime("%a, %d %b %Y %H:%M:%S GMT")
hashed = hmac.new(self.app_key.encode('utf8'), (f'x-date: {xdate}').encode('utf8'), sha1)
signature = base64.b64encode(hashed.digest()).decode()
authorization = (f'hmac username="{self.app_id}", algorithm="hmac-sha1"' +
f', headers="x-date", signature="{signature}"')
return {
'Authorization': authorization,
'x-date': xdate,
'Accept-Encoding': 'gzip'
}

Python 程式範例

我們來實際舉個例子，像是我想抓：

台鐵"台北"車站即時的列車到離站看板資訊，並且只要"逆行"的列車

先進到 PTX 平台的 Swagger 文件，找到 " 取得指定[車站]列車即時到離站電子看板 "：

列車即時到離站電子看板

(關於這些 Odata 的寫法，我在上一篇文章有說明，忘記的可以回去看看)

它顯示的 "Request URL" 長得像這樣：
https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?%24filter=Direction%20eq%201&%24format=JSON

接下來將這些代入程式中：

1
2
3
4


auth = Auth(app_id, app_key)
url = "https://ptx.transportdata.tw/MOTC/v2/Rail/TRA/LiveBoard/Station/1000?$filter=Direction eq 1&$format=JSON"
response = requests.get(url, headers=auth.get_auth_header())
print(response.json())

如此應該就能順利取得資料 🎉🎉🎉

完整 Python 程式範例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


import hmac
import base64
import requests
from datetime import datetime
from hashlib import sha1
app_id = '<YOUR APP ID>'
app_key = '<YOUR APP KEY>'
class Auth():
def __init__(self, app_id, app_key):
self.app_id = app_id
self.app_key = app_key
def get_auth_header(self):
xdate = datetime.utcnow().strftime("%a, %d %b %Y %H:%M:%S GMT")
hashed = hmac.new(self.app_key.encode('utf8'), (f'x-date: {xdate}').encode('utf8'), sha1)
signature = base64.b64encode(hashed.digest()).decode()
authorization = (f'hmac username="{self.app_id}", algorithm="hmac-sha1"' +
f', headers="x-date", signature="{signature}"')
return {
'Authorization': authorization,
'x-date': xdate,
'Accept-Encoding': 'gzip'
}
if __name__ == '__main__':
auth = Auth(app_id, app_key)
base_url = "https://ptx.transportdata.tw"
# 取得指定[車站]列車即時到離站電子看板(動態前後30分鐘的車次)
endpoint = "/MOTC/v2/Rail/TRA/LiveBoard/Station/1000"
filter = "Direction eq 1" # 順逆行: [0:'順行', 1:'逆行']
url = f"{base_url}{endpoint}?$filter={filter}&$format=JSON"
response = requests.get(url, headers=auth.get_auth_header())
print(response.json())

其他程式範例

除了參考我上面的 Python 範例，PTX 官方也提供不同程式語言的範例程式碼提供開發者下載 ( GitHub )。

平台提供
- ASP.NET
- Java
- JavaScript
網友提供
- Bourne Shell
- C# 與 .NET Standard 2.0
- Go
- Go Client SDK - Code generated by go-swagger
- Node.js
- python
- Ruby
- Swift
- PHP
- Postman

另外，在下一篇文章裡，我會分享 Google Apps Script 的範例程式，它跟一般 JavaScript 有一些些不同，Google Apps Script 中預設應該是不能使用 jQuery，還有編碼的寫法也有些不同。

結語

除了以上文章的解說，也可以看看官方的文件說明。
有針對 "航空"、"公車"、"雙鐵(台鐵/高鐵)" 資料做進一步的說明，如果有使用到此 API 服務的人，建議進入先了解。
* 不過我看此文件上次更新時間 2018/04/12，可能有些資料不是最新的。

上一篇了解 PTX 平台的說明與 OData 介面，本篇則教你如何透過 Python 程式來發出請求、獲取資料，快將你有趣的 idea 來動手做實現它吧~

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
公共運輸整合資訊流通服務平台 | 官網
 PTX 資料服務使用注意事項 | GitHub
PTX 官方範例程式碼 | GitHub

專注你喜歡的事，就能感受到那股強大的力量。

—— 戴資穎 (台灣羽球國手)

「PTX 公共運輸資訊平台」API 介紹 (含 Odata 說明)

jia@jiatool.com (Jia) — Sat, 23 Apr 2022 20:45:00 +0800

前言

你手機裡很可能有安裝臺鐵、高鐵、捷運、公車等等公共運輸的 APP，或者使用過查詢時刻表、動態相關網站( 示範應用列表 )，但他們是怎麼取得這些資料的呢？

原來有個政府的平台 — 公共運輸整合資訊流通服務平台，它整合並提供這些數據資料，以 Web API 的形式提供我們串接。

關於 PTX 平台我寫了三篇文章來介紹與程式教學：

「PTX 公共運輸資訊平台」API 介紹 (含 Odata 說明) <– 本篇
「PTX 公共運輸資訊平台」Python 範例
「PTX 公共運輸資訊平台」Google Apps Script 範例

PTX 公共運輸整合資訊流通服務平台

PTX 簡介

為了推動公共運輸整合資訊開放 (Open Data) 、統整各機關(構)的多元公共運輸資訊，交通部推出了這個 PTX 平台，包含了臺灣的公車、臺鐵、高鐵、捷運、航空、自行車、航運(海運)、觀光景點等公共運輸資料服務 API，非常的多樣，幾乎在臺灣你想的到的大眾交通工具都包在裡頭。
像是：臺鐵票價資料、高雄輕軌時刻表、臺北捷運即時通阻事件、機場即時入境航班、公車即時位置、公共自行車剩餘數量、觀光景點……等等。

PTX 網站有個「各項服務查詢」供檢視平台提供的服務，能依照 "領域類型"、"資料類型"、"業管機關" 去做篩選，每個服務還可以快速點開 API 說明及網址範例，另外還有整理成表格顯示：目前各單位資料供應現況表。

PTX 各項服務查詢

加入會員 & 取得 APP ID 與 APP Key

為了提供穩定的服務、加強資訊安全管理，要使用此平台的 API 前需要先加入會員。

加入會員

進入加入會員頁面，在此選擇「一般會員」即可，「進階會員」、「專案用戶」有更多的呼叫次數及其他權益，但那還要提供額外的證明，一般會員的 API 呼叫次數上限 20,000 次/日已經很夠我們自己玩玩，或做個小應用了。
(因為我以前註冊過，這邊就不演示了，按照網頁流程操作應該不會有什麼問題。)

申請加入 PTX 會員

取得 APP ID 與 APP Key

(APP ID 與 APP Key 下一篇文章使用 Python 實際操作時才會用到)

註冊完成並等待三個工作日審核後，會收到一封 Email，之後我們會使用到「基礎資料服務(L1)」的「APP ID」與「APP Key」。
而目前提供的資料服務多屬 L1，L2 的服務目前僅有場站空氣品質服務 (不知道現在 L2 是否有加入其他的服務)。

或者也可登入後到 API金鑰申請取得，如果忘記 APP Key 可點擊「忘記APP Key」即可，但要注意舊的 APP Key 就會失效，所以如果你 APP Key 不小心公開了也可由此來重新產生，避免額度被其他人使用。

取得 APP ID 與 APP Key

API 說明

可以參考官方提供的「資料使用葵花寶典」，此手冊分成以下四點作介紹說明

API 會員：各會員層級進行說明並提供會員申請流程。
API 使用說明：API 呼叫方法及注意事項進行說明。
API 特色說明：API 獨特的使用技巧進行說明。
API 資料使用注意事項：各運具資料面注意事項進行說明。

PTX 的 API 是以 OData（Open Data Protocol）標準介面格式對外開放供使用。

URI 設計概念

先來看看 URI 的設計概念。

這邊以臺鐵 "取得指定[日期],[車站]的站別時刻表資料" 為例：

臺鐵 "取得指定[日期],[車站]的站別時刻表資料"

從這張圖可以清楚的看出來，最前方 "基本網址" 大家都一樣，再來是 "API版本"、"鐵道" 中的 "臺鐵"，我們想抓的 "站別時刻表"，以及最後方帶入的參數 "車站代碼" 與 "日期"。
(車站代碼可以從另外一個 "車站基本資料" API 取得，或臺鐵官網的車站代碼表 )

雖然每項服務會有些不同，但其網址結構都是差不多的，這邊稍微知道就好，詳細說明請參考官方提供的「 API URI Convention文件」。

Swagger 文件工具

至於各項服務 API 說明可以從這裡進入，或到「 PTX 各項服務查詢」點擊對應服務右方的"服務說明"，它是透過 Swagger 這個文件工具來呈現。

這邊先講個 Swagger 基本使用。

找一個感興趣的資源(Resource)，並打開其 API 說明。

API 說明

大致分為幾個部分，最上方針對此資源簡短描述，再來 "Parameters" 是此資源可附加上的參數，像是我想看哪一個捷運系統的車站資料，就是在這邊帶上參數，除了標示 required 紅字為必填，其餘我們先暫時不必理會。最後 "Responses" 會寫到當回應哪個 HTTP Status Code 對應是哪個意思，其回應資料格式又是長什麼樣子。

API 說明

回應資料有些欄位可能看不出它代表意思，就可以到這邊找找說明。

API 說明

在 Parameters 與 Responses 中間有個大大的藍色 "Execute" 按鈕，我們給他用力按下去。

噹🌟！發現在底下 "Responses" 區塊跑出好幾個新東西：

"Request URL" 代表依照你上方設定的參數，其請求網址會長怎樣。
"Server response" 顯示回應 HTTP Status Code 及回應內容(Response body)，回應內容就是我們想要的資料啦~

API 回應說明

這個 Swagger 工具大致上的用法就是這樣。

到這邊，都可以如實拿到想要的資料了。

但可能它每次回傳的資料量很大，我只是需要其中的一部分資料而已，這樣會浪費頻寬、增加回應時間、接收到資料後還要費力處理，那有沒有能在送出請求時，就告訴 Server 我們想要那些資料呢？
有的！！接下來就要講到 Odata 這個介面格式厲害的地方了😮

Odata 查詢語法

通過 Odata 協定制定的用法，我們可以去做多樣的查詢、過濾、排序，甚至有更進階的函數語法。

我會依序介紹以下六種 Odata 的查詢方法：

$format 指定來源格式
$orderby 排序
$top 取前幾筆
$skip 跳過前幾筆
$select 挑選
$filter 過濾

這邊我是依照比較好理解的順序介紹說明，最後再舉幾個複合範例給各位參考。

$format 指定來源格式

指定回傳資料要以什麼格式。

PTX 提供 JSON 與 XML 兩種格式供選擇。

$format=json
$format=xml

$orderby 排序

指定回傳資料的排序。

升冪：由小到大；降冪：由大到小。

針對欄位1作升冪 (預設)
$orderby=Field1
$orderby=Field1 asc
針對欄位1作降冪
$orderby=Field1 desc
針對欄位1作升冪，欄位2降冪
$orderby=Field1 asc,Field2 desc

各 API 服務有不同的回傳資料，例如我在查詢公共自行車即時車位時，希望資料依照 "可租借數量" 由多至少排列：
$orderby=AvailableRentBikes desc

$top $skip 取前幾筆

這兩個是類似的概念。

$top：取前幾筆資料。
$skip 跳過前幾筆資料。

像是我想拿取前 11~30 筆資料：
$top=20&$skip=10

$select 挑選

指定只需要回傳那些欄位，多個欄位可用逗號(,)隔開，未指定則回傳全部欄位。
(目前只支援第一層欄位)

只回傳欄位1
$select=Field1
回傳多個欄位，欄位1和欄位2
$select=Field1,Field2

不過它有但書：

回傳資料指定為 json 時，只會回傳被 select 的欄位，除此之外，若其他欄位為非 nullable，也會回傳系統預設值。
回傳資料指定為 xml，沒有被指定的屬性若為 class 或是 string，不會回傳該欄位，但若是其他屬性(int,bool,enum..)，還是會回傳該欄位，其值為系統預設值。

$filter 過濾

(來到最複雜、最多變化的一個語法了😅)

filter 語法是用來對資料做篩選、過濾，提供「邏輯運算子」、「算術運算子」、「規範函數」、「Lambda Operators」可使用。

邏輯運算子 (Logical Operators)

邏輯運算子	意義
eq	等於
ne	不等於
gt	大於
ge	大於等於
lt	小於
le	小於等於
and	而且、和
or	或者
not	否定

例如想查詢公共自行車 "可租借數量" 大於 10 台的站點：
$filter=AvailableRentBikes gt 10
假如欄位是在第二層，則可透過 / 連接。
例如想取得高雄捷運 "左營站 " 的即時到離站電子看板：
$filter=StationName/Zh_tw eq '左營'

* 要注意後方比對的字串需使用單引號 ' 框起來，雙引號 " 是不行的哦。

算術運算子 (Arithmetic Operators)

算數運算子	意義
add	加
sub	減
mul	乘
div	除
mod	餘數

例如我想查詢有哪台公車目前時速是奇數：
$filter=Speed mod 2 eq 1
(知道這個好像也不能幹嘛……)

規範函數 (Canonical Functions)

規範函數	意義	規範函數	意義
substring	子字串	year	年份
startswith	字串開頭	month	月份
endswith	字串結尾	day	日
length	字串長度	hour	小時
indexof	指定字串出現位置	minute	分
tolower	字串變小寫	second	秒
toupper	字串變大寫	fractionalseconds	小數秒
trim	去空白	date	日期
contains	包含	time	時間
concat	串接
		round	四捨五入
		floor	無條件捨去
		ceiling	無條件進位
		cast	轉型

例如取得公車動態中車牌號碼開頭是 "001" 的資料：
$filter=startswith(PlateNumb, '001')
或者想知道車牌號碼長度為 7 個字的公車：
$filter=length(PlateNumb) eq 7
去台南旅遊，想找出店名包含 "豆花" 的店家：
$filter=contains(RestaurantName,'豆花')

Lambda Operators

Lambda Operators	意義
all	所有項目都要符合
any	其中一項符合

例如我想知道今天有哪幾班高鐵會停 "雲林"：
$filter=StopTimes/any(d:d/StationName/Zh_tw eq '雲林')

這部分可能一開始有些難懂，主要是用在判斷陣列中的值。
* 其中的 d 是可以隨意換其他名稱的。

多種複合用法

為了讓大家更容易理解，這邊我再舉幾個多種語法所組合的用法：

想看看高鐵在今年(2022年) 3 月之後有發布什麼關於 "左營" 的最新消息：
$filter=year(PublishTime) eq 2022 and month(PublishTime) ge 3 and contains(Title,'左營')
(啊…4/1 水泥施工事故導致電力異常，台南-左營站間停駛)
台南市公車中，路線是 "紅" 字開頭，並且目前 "時速超過 30 公里"，依照時速由大排到小的前五名：
$filter=startswith(SubRouteName/Zh_tw,'紅') and Speed gt 30&$orderby=Speed desc&$top=5
因為提著大包小包，想知道台北捷運 "古亭站" 有哪個出口有 "電扶梯" 或 "電梯"，且只回傳 "出口" 和 "地址"：
(備註：Escalator 是否有電扶梯(0:沒有,1:雙向,2:出站,3:入站))
$select=ExitName,LocationDescription&$filter=StationName/Zh_tw eq '古亭' and (Escalator ne 0 or Elevator eq true)

有關如何使用 Odata 查詢 PTX API 資料，官方有整裡個簡報—「 PTX APIs開發技術說明(含Odata) 」，裡頭有更詳細地介紹 Odata，以及其查詢選項、函數語法。

當然，如果你覺得這些篩選語法太麻煩，也是可以全部抓下來後，再使用程式去處理。

API 呼叫統計

PTX 平台也提供「服務呼叫統計」網頁，可查看自己目前的資料數據傳輸量、呼叫次數以及虛擬點數等等統計數據，確認還有多少額度可以使用，甚至也針對各項服務做統計。

PTX 服務呼叫統計

結語

有了這個 PTX 平台後，想要取得各大眾公共運輸的資料變得相當容易，除了做成應用程式自用外，也可以公開讓大家使用。

官方也有整理一些常見問題供參考。

如何？看完介紹後你腦中是否產生有趣的 idea 了呢😙
別急，下一篇文章會來教你該如何使用 Python 來串接 PTX API ，以及需要注意什麼事情。

歡迎追蹤『 IT空間』FB 粉專，取得最新發文通知🔔

參考：
公共運輸整合資訊流通服務平台 | 官網
 PTX 資料使用葵花寶典
 PTX API 說明 | Swagger
PTX APIs開發技術說明(含Odata)

等待奇蹟，不如為自己留下努力的軌跡；期待運氣，不如堅持自己的勇氣。

—— 李洋 (台灣羽球國手)