# 公車API動態資料使用注意事項
### **\[逐筆更新]與\[批次更新]之資料服務差異**
| | 逐筆更新 | 批次更新 |
| ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| 通訊方式 | UDP | TCP |
| 特色 | 資料可能丟失，但延遲時間較少 | 保證資料送達，但延遲時間較多 |
| N1資料之預估到站時間 | 僅在公車離站時觸發車機更新，不提供自動倒數，需使用者自行處理時間遞減機制
可詳見下方\[逐筆更新]動態資料說明第二點
| 每30秒公總會更新一次(由公總加值)，但仍需注意在下一次更新前的延遲時間
可詳見下方表格：\[批次更新]動態資料傳遞延遲
|
| 資料整併 | 公總無額外處理：同一站同一路線只會有一筆最近的預估到站時間 | 公總提供額外加值：將同一站同一路線的多筆預估到站時間整併，提供最快到站的時間 |
| 即時性 | 約2\~3秒 | 60秒(每分鐘更新一次)
可詳見下方表格：\[批次更新]動態資料傳遞延遲
|
{% hint style="info" %}
**UDP說明**
當離開B站時，才會觸發車機更新並推播預估到站資訊，同時也不會提供每一路線各站的N1資訊，僅出現部分路線/站牌有預估到站時間。
以上圖為例，N1的API呼叫結果中，僅有B、C、D、E站提供資訊。
{% endhint %}
{% hint style="info" %}
**TCP說明**
公總加值後，每分鐘更新1871路線底下每一附屬路線(THB187101、THB187102、THB1871A1、THB1871A2)於每站的預估到站資訊。
以上圖為例，N1的API呼叫結果中，A、B、C、D、E站皆提供資訊。
{% endhint %}
### \[逐筆更新(UDP)]動態資料說明
1. 逐筆更新資料服務目前僅**公總(國道客運)及其代管縣市**提供，公總代管縣市包含：基隆市、新竹縣市、苗栗縣、南投縣、彰化縣、雲林縣、嘉義縣市、屏東縣、宜蘭縣、花蓮縣、臺東縣、澎湖縣。
2. 關於逐筆更新之N1資料，其預估到站時間需使用者自行處理時間遞減機制，或以EstimateTime-(收到資料時間-SrcTransTime)作為實際預估抵達時間。
### \[批次更新(TCP)]動態資料說明
1. \[批次更新]動態資料傳遞延遲
公路客運六都市區公車動態資料延遲時間（來源端—本平臺）：
| 與來源抓取頻率 | A1 | A2 | N1 |
|---|
| 與來源抓取頻率 | A1 | A2 | N1 |
| 公總與代管縣市 | 約5秒 | 約5秒 | 約5秒 |
| 臺北市 | 約5秒 | 約5秒 | 約5秒 |
| 新北市 | 約5秒 | 約5秒 | 約5秒 |
| 桃園市 | 約15秒 | 約30秒 | 約20秒 |
| 臺中市 | 約15秒 | 約30秒 | 約20秒 |
| 臺南市 | 約15秒 | 約15秒 | 約30秒 |
| 高雄市 | 約10秒 | 約30秒 | 約20秒 |
| 連江縣 | 約10秒 | 約10秒 | 約20秒 |
| 金門縣 | 約10秒 | 約30秒 | 約20秒 |
* 延遲時間為SrcUpdateTime與UpdateTime時間差。
* 上述其他非六都與離島縣市皆由公總動態系統代為管理提供，故同公總動態延遲時間。
* 臺中市與高雄市延遲較長是因為來源端本身有作Cache機制，故即使TDX每6秒跟來源端Polling更新一次，仍無法即時更新資料。
### \[逐筆更新]與\[批次更新]動態資料共通說明
#### 動態資料更新時間資料說明
| 更新時間項目 | 中文名稱說明 | 發生時間 | 範例 |
|---|
| 更新時間項目 | 中文名稱說明 | 發生時間 | 範例 |
| GPSTime | 車機時間 | 最早 | 2017-11-22T11:24:38 |
| TransTime | 車機資料傳輸時間 | 次早 | 2017-11-22T11:24:39 |
| SrcRecTime | 來源端平臺接收時間 | | 2017-11-22T11:24:40 |
| DataTime | 系統演算該筆 預估到站資料的時間 | | 2017-11-22T11:24:44 |
| SrcUpdateTime | 來源端平臺資料更新時間 | 批次更新用 | 2017-11-22T11:24:53 |
| SrcTransTime | 來源端平臺資料傳出時間 | 推播系統用 | 2017-11-22T11:24:53 |
| UpdateTime | 本平臺資料更新時間 | 最晚 | 2017-11-22T11:24:58 |
備註：當部分時間邏輯順序不對時，可能原因為系統來源端未將系統做好校時工作。
1. 公路客運及公總代管的縣市N1訊息中雖沒有提供路線第1站之下一班車時刻資訊，但可從靜態資料的時刻表與動態GPS點位資料做關連加值，例如：當車子已經駛離起始站後，N1中的第1站預估到站就可以換成顯示下一班的時刻資訊。
2. 公路路線ID編碼與實際站牌上顯示路線編號可能會有不一致的情況，如1659路線為例：當時此路線建置時，因共有3條主支線，該路線實際站牌資訊以1659A、1659B、1659C表達；然而在公路總局內部管理使用則以主支線方式1659、1659A 、 1659B做為區別，故建議參考公路客運i\_Bus中，以桃園市八德區→國道3號→新北市土城區\[經建國路]、\[經介壽路]、\[大湳至土城班次]呈現路線名稱為宜 ，提醒各加值業者在使用上必須注意。
3. 公車N1資料經確認過班表資料後，若發現某些路線似乎沒有公車時刻的資料原因主要有兩者
* 司機車機系統未開啟。
* 當下若非路線營運時間，就無預估到站資料。如：公總8232A2路線為例：班表顯示周一至五都有營運，但查詢A1及N1資料時皆無8232A2資料，因為此路線一天只有一班，營運時間僅為06:10，故當您搜尋時間非此時間附近，就無此筆資料。
4. 為何預估到站資料（N1）有些有車牌號碼有些沒有？而有時候該值為負值？
* 部分縣市（如臺北市）並沒有在預估到站資料（N1）中提供車牌號碼欄位資料。
* 公總預估到站資料（N1）中，有時該值為＂**-1**＂，當發生此狀況時，表示**車輛已過該站**，例如某路線共有10個站，若某車牌已經通過第3站，則其第1站到第3站的預估到站資料的車牌號碼欄位值將為＂-1＂且其預估到站時間欄位不會有值，而第4站到第10站的車牌號碼及預估到站欄位都會有值。
5. 全臺市區公車、公路客運提供預估到站時間資料（N1）之作法說明：
* 若同一路線上同時有多台車在線上進行服務時，N1資料將會進行相關的聚合（Aggregation），**僅提供距該路線最近車輛之預估時間資料**。
* 桃園市、臺中市、高雄市之N1資料，針對車輛已過站之站牌(車牌號碼PlateNumb為 ""，車輛狀態備註StopStatus為1:未發車者)，不會提供下班車的EstimateTime到站時間預估(秒)。
6. 公路總局及代管縣市之預估到站N1資料內IsLastBus欄位說明：
* 當該路線上在沒有車輛行駛、沒有到離站訊息的情況下，就不會觸發預估到站時間的演算，也就不會有預估到站N1資訊，因此EstimateTime為空值Null。
* 當系統偵測到該路線的末班車有行駛時，IsLastBus才會為1。
* 實務上發生過，某路線一天只發一班車（如：8223A2路線），且某日發生沒有車輛行駛且沒有到離站訊息的狀況，故依前述第1項，就不會觸發預估到站時間演算，該路線EstimateTime值則為空值Null，IsLastBus欄位為0。\
造成加值業者若僅依IsLastBus欄位來判別「是否為末班車」之誤判情形，故經洽公路總局建議加值業者可新增下列邏輯加以處理，以避免此種誤判情形。
* 同公總App顯示方式，使用「末班資訊」文字，取代「末班車已過」。
* 為App新增額外判斷程式，該判斷邏輯為：若EstimateTime欄位為Null且欄位isLastBus=0，則顯示「末班資訊」。
* 當使用者點選「末班資訊」，可顯示下列文字「末班車資訊請電洽：XX客運，電話：XX-XXXXXXXX」。
7. 公路總局及代管縣市之預估到站N1資料DataTime與SrcTransTime欄位補充說明：
* 公總N1資料現在是「固定一分鐘傳送一次全部路線的N1」到TDX平臺，傳送方式採TCP協定拆分成多數個封包連續不斷推播進TDX平臺，原則上，SrcTransTime一樣，就表示屬於同一批全部路線N1資料的傳送，但因為資料很多，一秒沒辦法全部送完，所以可能不會全部訊息的SrcTransTime都完全一樣，故可能會在幾秒的前後範圍內。
8. 資料傳送時間（SrcTransTime）- 資料演算時間（DataTime） 之差值若超過1分30秒以上，或甚至超過30分以上，皆屬正常，主要原因分述如下：
* 當預估到站時間倒數到59秒內之後，就不會再更新預估到站時間，直到車輛實際進站後才會再更新，這種狀況下就可能會有SrcTransTime - DataTime 這個差值超過 1分30秒以上的狀況發生。
* 舉例來說，某路線出第2站時，系統預估到第3站的時間為10分鐘，接下來，每一分鐘系統會自動倒數，從10分鐘遞減到9、8、7...，但如果車輛實際行駛是15分鐘，那10分鐘之後就倒數到0分鐘（N1倒數到小於59秒），因預估時間不能有負值，所以11分\~15分之間預估時間就停住不更新了，此時公總App跟便民網頁就是一直顯示進站中。
9. 由於公總系統提供的N1開放資料是固定每分鐘更新一次，而公總App跟便民網頁是直接存取公總內部系統的即時資料庫，故常會導致部分加值業者反應TDX平臺資料跟公總App與便民網站部份資料不太一致的情況，而公總考量系統資料量龐大，仍維持1分鐘批次更新N1資料1次，請加值業者使用此資料時務必注意。
10. 公路總局及代管縣市之公車動態定時A1資料使用提醒：\
針對公總系統之公車動態定時A1資料，TDX平臺會即時更新並保留每台車輛最新ㄧ筆的GPS點位資訊，惟考量部分車機訊號會因故較慢（超過好幾分鐘以上）回傳，故TDX平臺會保留每台車輛最近2小時內的最新ㄧ筆資料，請加值業者使用該項資料時需特別注意。\
備註：
* 系統持續更新，整體只會有最新兩小時內的資料。
* 部分縣市因公車路線數量少、班次數少，故有時會發生A1資料中的SrcTransTime，停留在30分或1個小時以前的資料，使用時請注意。
11. 公路總局及代管縣市之公車動態定點A2資料使用提醒：\
針對公總系統之公車動態定點A2資料，原則不定期更新，TDX平臺會即時更新並保留每台車輛最新ㄧ筆的車機定點資訊（到站/離站），惟考量有時公路/國道客運路線之站間距離較長，需經過較長的時間才會更新A2資料，故TDX平臺會保留每台車輛最近2小時內的最新ㄧ筆資料，請加值業者使用該項資料時特別注意。\
備註：系統持續更新，整體只會有最新兩小時內的資料。
12. 公路總局及代管縣市之公車預估到站N1資料使用提醒：\
針對公總系統之公車預估到站N1資料，更新時間依\[逐筆更新]或\[批次更新]而不同，TDX平臺會即時更新並保留每條路線站牌上最新一筆預估到站資訊，惟考量有時來源端資料因故未及時更新、來源端網路中斷、與來源端網路間傳輸問題等，故TDX平臺會保留每條路線最近2小時內最新的預估到站資料，請加值業者使用該項資料時特別注意。\
備註：系統持續更新，整體只會有最新兩小時內的資料。
13. 公車動態A1及A2相關狀態Status代碼意義補充說明：
* DutyStatus（'0:正常'；'1: 開始'；'2:結束'）：0通常是車機剛開機才會顯示的值，表示車輛尚未正式發班；1是指一般車機處於行駛之狀態，表示車輛已開始執勤；2是車機行經公車路線之末端站位後，表示車輛已完成任務。
* BusStatus（'99: 非營運狀態'）：99通常為該車輛不提供服務或車內場站調度或去執行專車/加油...等任務才會切換的狀態，系統會伴隨DutyStatus = 2（結束），公車動態系統不會預估該車輛之預估到站時間，以避免影響動態正確性。
14. 針對公車動態A2資料，演算新增輸出預估起始發車時間資訊：
* TripStartTimeType 班次發車時間類型: 0:實際發車時間；1:預估發車時間；2 :無法推估發車時間。
* TripStartTime 首站發車時間，若有第一站的實際發車時間，則填實際發車時間；若無首站發車時間，以站間旅行時間推估首站發車時間；若無第一站的實際發車時間且該路線無站間旅行時間，則無法推估發車時間。
