# 雙鐵API資料使用注意事項

## 靜態資料

1. **雙鐵臨時加班資訊：**

   雙鐵僅提供前一天異動資訊，目前**尚無法提供當日臨時加班資訊**。
2. **定期時刻表與每日時刻表之差異：**

   為確保時刻表的正確性及即時性，臺鐵提供近60天每日時刻表、高鐵提供近45天每日時刻表，然而考量國內外旅客對於在臺旅行常需在數個月前規劃行程，故，若需超過此段期間之時刻表資料則可參考定期時刻表，其有助於未來數個月後之旅運規劃服務（通常國外旅客來臺觀光較需要使用定期時刻表資料）。
3. **車站代碼（StationID）與車站簡碼（StationCode）之差異：**
   * **StationID**通常為列車排點系統的車站代碼系統，時刻表資料中即以此代碼為主。
   * **StationCode**主要是票務系統如訂票系統用的車站簡碼，加值業者使用時必須先了解其差異與使用時機。
4. #### UpdateTime 與 UpdateInterval 欄位說明

   UpdateInterval為平臺向來源資料抓取的頻率，靜態資料每4小時(14,400秒)與來源抓取一次，若來源資料無異動，則不進版更新(UpdateTime停留在上次進版時間)；若來源資料有異動，則UpdateTime更新為本次進版時間。

## 動態資料

1. 台鐵列車到離站動態即時電子看板資料（Liveboard），目前延遲時間為2分鐘，該資料與臺鐵官網的列車動態資料來源一致，但與車站或月台上即時顯示的TIDS看板並非一致，會有時間上的延遲，故加值業者在該項資料使用上，請注意並請勿直接與車站或月台上的TIDS看板進行比對，並提醒民眾進入車站主體後，即請以車站內部系統顯示的動態資訊為主。
2. **「列車即時準點/誤點資料」與「車站別列車即時到離站電子看板資料」之差異：**

   「列車即時準點/誤點資料」為臺鐵提供的原始資料，由於該項資料當初僅提供**車次代碼**與**誤點時間**兩個欄位，本平臺為利各加值單位應用，透過臺鐵提供的每日列車時刻表，轉換成每日站別時刻表，並將其與「列車即時準點/誤點資料」進行關聯，產製全臺各車站之前後30分鐘「車站別列車即時到離站電子看板資料」，由於本項資料為加值轉換所得，非由臺鐵各車站直接介接取得，故請加值業者審慎使用，或自行設計演算邏輯轉換處理。
3. **高鐵對號座即時剩餘位({原始}列車區段Leg角度)資料使用注意事項：**\
   本API以天為單位，取得指定日期各車次可上車之站點座位剩餘情況，當日(D)之更新頻率為每10分鐘，當日後27日(D+1\~D+27)之更新頻率為每日的10、16、22時。以下資料為例：

```
{
      "TrainNo":"0117",
      "Direction":0,
      "StartingStationID":"0990",
      "StartingStationCode":"NAK",
      "StartingStationName": {
         "Zh_tw":"南港",
         "En":"Nangang"
         },
      "EndingStationID":"1070",
      "EndingStationCode":"ZUY",
      "EndingStationName": {
         "Zh_tw":"左營",
         "En":"Zuoying"
         },
      "StopStations": 
      [
         {
         "StopSequence":"1",
         "StationID":"0990",
         "StationCode":"NAK",
         "StationName": {
            "Zh_tw":"南港",
            "En":"Nangang"
             },
         "NextStationID":"1000",
         "NextStationCode":"TPE",
         "NextStationName": {
            "Zh_tw":"台北",
            "En":"Taipei"
             },
         "StandardSeatStatus":"O",
         "BusinessSeatStatus":"O"
         },
         {
         "StopSequence":"2",
         "StationID":"1000",
         "StationCode":"TPE",
         "StationName": {
            "Zh_tw":"台北",
            "En":"Taipei"
             },
         "NextStationID":"1010",
         "NextStationCode":"BAC",
         "NextStationName": {
            "Zh_tw":"板橋",
            "En":"Banciao"
             },
         "StandardSeatStatus":"X",
         "BusinessSeatStatus":"L"
         },
         {
         "StopSequence":"3",
         "StationID":"1010",
         "StationCode":"BAC",
         "StationName": {
            "Zh_tw":"板橋",
            "En":"Banciao"
             },
         "NextStationID":"1040",
         "NextStationCode":"TAC",
         "NextStationName": {
            "Zh_tw":"台中",
            "En":"Taichung"
             },
         "StandardSeatStatus":"O",
         "BusinessSeatStatus":"O"
         },
       {
      "StopSequence":"4",
      "StationID":"1040",
      "StationCode":"TAC",
      "StationName": {
         "Zh_tw":"台中",
         "En":"Taichung"
          },
      "NextStationID":"1070",
      "NextStationCode":"ZUY",
      "NextStationName": {
         "Zh_tw":"左營",
         "En":"Zuoying"
          },
      "StandardSeatStatus":"O",
      "BusinessSeatStatus":"O"
      }
    ]
}
```

**以文字的方式解讀為：** \
該指定日期有0117這個車次，該車次為南港發車開往左營的列車，從南港站發車後會在臺北、板橋、臺中停靠，目前除了臺北站標準車廂售完(X)、商務車廂即將售完(L)外，其它站點皆有充足剩餘座位(O)。 \
實際運用在旅程規劃時，需留意啟程車站及行經車站是否有座位已售完的狀況，因為**資料中呈現的是該車次於該站點是否尚有座位**，故規劃時需考量上車及行經車站中是否有售完之情況(下車車站不需考慮)。 \
接下來再以圖形化、實際旅程起迄解讀前述資料：  

![](/files/mlMjnQthsADBhDBzcN66)

{% hint style="info" %}
因為臺北站的標準車廂為售完(X)、商務車廂為即將售完(L)，其它車站皆有充足座位(O)，所以搭乘情境舉例如下：

* 從南港搭乘至臺北站是標準、商務皆有充足的座位數，因為上車的車站南港目前標準、商務皆為充足(O)，(下車車站不需考慮是否尚有座位)。 \
  從南港搭乘至板橋，目前僅剩少量的商務車廂座位，雖然從南港上車時標準、商務皆為充足(O)，但是標準車廂剩餘的座位已賣給臺北站上車的旅客，所以要從南港到達板橋的旅客可以選擇商務車廂或是將旅程分段(一段商務車廂一段標準車廂或其它運具)或選擇其它車次。
*  從南港要搭至臺中也是一樣的情況，因為臺北站上車的旅客已將標準車廂座位買走，所以雖然南港站上車時看的到座位，但無法買到從南港坐到臺中的座位。(同前述案例可以選擇商務車廂/旅程分段/其它車次) 
* 從臺北搭乘至板橋，因為從臺北站搭車的旅客較多，其它旅客已將標準車廂座位買走，無法買到臺北至板橋的座位。(同前述案例可以選擇商務車廂/其它車次) 
* 其餘從板橋或臺中搭乘的起迄則因為避開座位已售完的臺北站，故標準、商務車廂座位皆充足可購買。 
  {% endhint %}

換句話說，解讀本API時，首先應**確認是否有符合搭乘起迄的車次，並留意該車次的上車車站、行經車站是否尚有座位**。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://motc-ptx.gitbook.io/tdx-zi-liao-shi-yong-kui-hua-bao-dian/data_notice/public_transportation_data/rail_data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.