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

前言

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

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

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

取得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 認證授權機制

詳細步驟說明如下:

取得 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 平台常見問題 | 官網

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

🔻 如果覺得喜歡，歡迎在下方獎勵我 5 個讚~