公車API資料使用注意事項

靜態資料

  • 站牌與站位兩者間之差異

    • 站牌Stop:一站牌點位若有多條公車路線行經,而各個公車路線擁有各自站牌桿時,就會有多筆站牌資料,每個站牌有分去程或返程。
    • 站位Station將道路同側、附近同一集群的站牌聚合過後的抽象點位,用來代表該處公車站位。
    • 站名碼StationName:公車「站名代碼」資料,與站牌、站位不同,無區分路線及方向性(不分去程或返程),通常供票證資料OD旅次分析使用。

      如:StationUID為TPE50629(劍潭去程),PositionLat: 25.0807666778564,PositionLon: 121.524398803711,此站位只有一筆經緯度資料。目前僅有台北市、新北市、公路總局提供站位資料,其餘縣市尚無法提供。

路線站序與顯示越路線站序差異圖

  • 為何有些公車路線GIS線型資料分去返程(分2條線型圖資),有些卻沒有分(只有1條線型圖資)?

    此現象係為來源端供應資料現狀,目前六都線型資料中僅台北與新北沒有分去返程,其餘縣市皆有分去返程,標準Inbound說明文件已將Direction去返程納入線型資料。

  • 公路客運路線ID的編碼原則

    • 前四碼為路線代號
    • 第五碼為正副路線資訊 (A:主路線,B:副路線)
    • 第六碼為去返程資訊 (1:去程,2:返程),如:路線ID為7011A2,代表此筆當時為7011主路線返程資料。
  • 部分欄位若為空值是因來源單位尚未提供介接

    如:新北市N1資料因來源單位未提供StopStatus、NextBusTime、SrcRecTime及SrcUpdateTime資料,故以上欄位皆為空值。

  • 新北市【NewTaipei】來源

    V1版資料由既有公車動態系統介接; V2版資料由雙北雲系統介接,106年度因來源系統變更,故將新北介接來源調整為Data.taipei。

  • 為何公車的路線站牌、時刻表資料(StopOfRoute)會多一個營運業者(OperatorID)欄位?

    考量公路客運及市區公車資料屬性一致性,且來源端公路客運資料的特性同一站牌會因為分屬不同的客運業者而有不同的StopID,而預估到站資料(N1)中的StopID會與其對應,故加值業者在使用公總的StopOfRoute時,要注意對於同一路線由兩個或多個不同客運業者經營時,會有依營運業者而有不同StopOfRoute之多套清單現象。

  • 顯示用路線站序(DisplayStopOfRoute)資料與路線站序(StopOfRoute)資料之差異

    • 路線站序(StopOfRoute)資料是用來儲存每條路線/附屬路線實際跑法的站序資料。
    • 實務上,有些路線中間會存在分叉後又合併之狀況(如307經西藏路、307經莒光路),所以會存在多條附屬路線的情況,此情況會導致加值業者在APP端或網頁前端不易顯示路線分支狀況,故部分縣市(如台北市及新北市)為求簡易的顯示路線站序,會定義顯示用路線站序(DisplayStopOfRoute)資料[即台北市與新北市的Stop資料],嘗試以線性(Leanerly)方式來顯示該路線所有的站序,並輔以預估到站(N1)資料疊合,讓民眾於一個頁面就清楚明瞭該路線(如:307路線)所有車輛(同時含307經西藏路、307經莒光路)的預估到站資料。

      路線站序與顯示越路線站序差異圖

      • 當某特定路線下不存在任何其他附屬路線時,其路線站序(StopOfRoute)資料內容會完全等同於顯示用路線站序(DisplayStopOfRoute)資料。
      • 以前顯示用路線站序(DisplayStopOfRoute)是併同在路線站序(StopOfRoute)資料中,並以KeyPattern欄位進行區分,但由於多數加值業者反應將此兩項資料加以區分以利使用,因此針對部分縣市(如台北市及新北市)新增提供顯示用路線站序(DisplayStopOfRoute)資料,並將原路線站序(StopOfRoute)中的KeyPattern欄位刪除及將相對應的資料搬移至顯示用路線站序(DisplayStopOfRoute)資料中。
  • 公車時刻表資料:

    部分市區公車路線的時刻表資料(如台北市255路線),同時會包含班距的時刻與班表的時刻(如:晚上9:00前採固定班距,之後採固定時刻表);另外公路總局及其代管系統縣市(除六都+基隆+連江+金門)之時刻表資料,不一定含全部站點的時刻資料,有些只有重要站點才有時刻資訊;有些只有路線起始站(第1站)才有時刻資訊。

  • 公路客運路線時刻表資料,會因同一路線由多家客運業者聯營,故會有不同客運業者有不同時刻表資料之情形。

  • 起迄站中英文名稱:

    此資料欄位由各縣市來源單位提供,部分縣市並非以路線起迄站名稱提供,而是以平常慣用的路線Headsign的起迄名稱。另部分縣市如台南縣市,目前提供的迄站名稱中,並非只放一個站名,尚包含中間站名,例如:台南 [黃6] 路線的迄站名稱,放的是「白沙屯 ─ 後壁火車站」而非「後壁火車站」,加值業者在使用時請多加留意。

  • 站牌點位資料品質:

    部分縣市站牌點位座標經緯度值為0 (如:基隆市),是因為部分縣市站牌點位的盤點清查作業正在進行中,來源單位為確保資料正確性,將於資料盤點確認完畢後才能正式提供,故需耐心等候一段時間。另有關站牌點位座標的品質,交通部空間檢核技術團隊將持續於每月提供資料品質檢測報表給各相關來源單位請求修正並精進品質。

  • 路線資料內HasSubRoute欄位說明:

    此欄位值與SubRoutes結構並無強烈的絕對關聯,因為有些縣市有定義附屬路線 [如:台北/新北/公總/公總系統代管縣市],且無論有無實際上的附屬路線,都會賦予其SubRouteID;有些縣市雖無定義附屬路線 [如:四都(除台北/新北))/基隆/金門],但基於資料一致性,本平台仍會為其產製一份相對應的附屬路線資料(若有去返程,則會有兩筆),以便於統一資料格式。

動態資料

  • 動態資料傳遞延遲

    公路客運六都市區公車動態資料延遲時間(來源端—本平臺):

動態資料延遲時間
公總 即時推播,約2~3秒
台北市 約10秒
新北市 約10秒
基隆市 約10秒
桃園市 約30秒
台中市 約60秒
台南市 約20秒
高雄市 約30秒
連江縣 約20秒
金門縣 約30秒

※延遲時間為SrcUpdateTime與UpdateTime時間差。

※上述其他非六都縣市皆由公總動態系統代為管理提供,故同公總動態延遲時間。

※台中市與高雄市延遲較長是因為來源端本身有作Cache機制,故即使PTX每6秒Polling跟來源端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

※當部分時間邏輯順序不對時,可能原因為系統來源端未將系統做好校時工作。

  • [逐筆更新]與[批次更新]之資料服務差異(目前僅公總提供逐筆更新)
逐筆更新 批次更新
通訊方式 UDP TCP
特色 資料可能丟失,但延遲時間較少 保證資料送達,但延遲時間較多
N1資料之預估到站時間 僅在公車離站時觸發車機更新(不提供自動倒數※) 每1分鐘公總會更新一次(由公總加值),但仍需注意在下一次更新前的延遲時間
資料整併 公總無額外處理:同一站同一路線將有多筆預估到站時間 公總提供額外加值:將同一站同一路線的多筆預估到站時間整併,提供最快到站的時間

※使用者需自行處理時間遞減機制,或以EstimateTime-(收到資料時間-SrcTransTime)作為實際預估抵達時間。

  • 公路客運及公總代管的縣市N1訊息中雖沒有提供路線第1站之下一班車時刻資訊,但可從靜態資料的時刻表與動態GPS點位資料做關連加值,例如:當車子已經駛離起始站後,N1中的第1站預估到站就可以換成顯示下一班的時刻資訊。
  • 公路路線ID編碼與實際站牌上顯示路線編號可能會有不一致的情況,如1659路線為例:當時此路線建置時,因共有3條主支線,該路線實際站牌資訊以1659A、1659B、1659C表達;然而在公路總局內部管理使用則以主支線方式1659、1659A 、 1659B做為區別,故建議參考公路客運i_Bus中,以桃園市八德區→國道3號→新北市土城區[經建國路]、[經介壽路]、[大湳至土城班次]呈現路線名稱為宜 ,提醒各加值業者在使用上必須注意。
  • 公車N1資料經確認過班表資料後,若發現某些路線似乎沒有公車時刻的資料原因主要有兩者
    • 司機車機系統未開啟
    • 當下若非路線營運時間,就無預估到站資料。如公總8232A2路線為例:班表顯示周一至五都有營運,但查詢A1及N1資料時皆無8232A2資料,因為此路線一天只有一班,營運時間僅為06:10,故當您搜尋時間非此時間附近,就無此筆資料。
  • 為何預估到站資料(N1)有些有車牌號碼有些沒有?而有時候該值為負值?

    (1) 部分縣市(如台北市)並沒有在預估到站資料(N1)中提供車牌號碼欄位資料。

    (2) 公總預估到站資料(N1)中,有時該值為"-1",當發生此狀況時,表示車輛已過該站,例如某路線共有10個站,若某車牌已經通過第3站,則其第1站到第3站的預估到站資料的車牌號碼欄位值將為"-1"且其預估到站時間欄位不會有值,而第4站到第10站的車牌號碼及預估到站欄位都會有值。

  • 全台市區公車、公路客運提供預估到站時間資料(N1)之作法說明:

    若同一路線上同時有多台車在線上進行服務時,N1資料將會進行相關的聚合(Aggregation),僅提供距該路線最近車輛之預估時間資料

  • 公路總局及代管縣市之預估到站N1資料內IsLastBus欄位說明:

    (1) 當該路線上在沒有車輛行駛、沒有到離站訊息的情況下,就不會觸發預估到站時間的演算,也就不會有預估到站N1資訊,因此EstimateTime為空值Null。

    (2) 當系統偵測到該路線的末班車有行駛時,IsLastBus才會為1。

    (3) 實務上發生過,某路線一天只發一班車(如8223A2路線),且某日發生沒有車輛行駛且沒有到離站訊息的狀況,故依前述第(1)項就不會觸發預估到站時間演算,該路線EstimateTime值則為空值Null,IsLastBus欄位為0。
    造成加值業者若僅依IsLastBus欄位來判別「是否為末班車」之誤判情形,故經洽公路總局建議加值業者可新增下列邏輯加以處理,以避免此種誤判情形。

    • 同公總APP顯示方式,使用「末班資訊」文字,取代「末班車已過」。
    • 為APP新增額外判斷程式,該判斷邏輯為:若EstimateTime欄位為NULL且欄位isLastBus=0,則顯示「末班資訊」。
    • 當使用者點選「末班資訊」,可顯示下列文字「末班車資訊請電洽: XX客運,電話: XX-XXXXXXXX」。
  • 公路總局及代管縣市之預估到站N1資料DataTime與SrcTransTime欄位補充說明:

    • 公總N1資料現在是「固定一分鐘傳送一次全部路線的N1」到PTX平台,傳送方式採TCP協定拆分成多數個封包連續不斷推播進PTX平台,原則上,SrcTransTime一樣,就表示屬於同一批全部路線N1資料的傳送,但因為資料很多,一秒沒辦法全部送完,所以可能不會全部訊息的SrcTransTime都完全一樣,故可能會在幾秒的前後範圍內。
    • 資料傳送時間(SrcTransTime) - 資料演算時間(DataTime) 之差值若超過1分30秒以上,或甚至超過30分以上,皆屬正常,主要原因分述如下:

      a. 當預估到站時間倒數到59秒內之後,就不會再更新預估到站時間,直到車輛實際進站後才會再更新,這種狀況下就可能會有SrcTransTime - DataTime 這個差值超過 1分30秒以上的狀況發生。

      b. 舉例來說,某路線出第2站時,系統預估到第3站的時間為10分鐘,接下來,每一分鐘系統會自動倒數,從10分鐘遞減到9、8、7......,但如果車輛實際行駛是15分鐘,那10分鐘之後就倒數到0分鐘(N1倒數到小於59秒),因預估時間不能有負值,所以11分~15分之間預估時間就停住不更新了,此時公總APP跟便民網頁就是一直顯示進站中。

    • 由於公總系統提供的N1開放資料是固定每分鐘更新一次,而公總App跟便民網頁是直接存取公總內部系統的即時資料庫,故常會導致部分加值業者反應PTX平台資料跟公總App與便民網站部份資料不太一致的情況,而公總考量系統資料量龐大,仍維持1分鐘批次更新N1資料1次,請加值業者使用此資料時務必注意。

  • 公路總局及代管縣市之公車動態定時A1資料使用提醒:

    目前公總系統之公車動態定時A1資料,原則每20-30秒更新一次,PTX平臺會即時更新並保留每台車輛最新ㄧ筆的GPS點位資訊,惟考量部分車機訊號會因故較慢(超過好幾分鐘以上)回傳,故PTX平臺會保留每台車輛最近2小時內的最新ㄧ筆資料,請加值業者使用該項資料時需特別注意。

    備註:

    • 系統持續更新,整體只會有最新兩小時內的資料
    • 部分縣市因公車路線數量少、班次數少,故有時會發生A1資料中的SrcTransTime,停留在30分或1個小時以前的資料,使用時請注意
  • 公路總局及代管縣市之公車動態定點A2資料使用提醒:

    目前公總系統之公車動態定點A2資料,原則不定期更新,PTX平臺會即時更新並保留每台車輛最新ㄧ筆的車機定點資訊(到站/離站),惟考量有時公路/國道客運路線之站間距離較長,需經過較長的時間才會更新A2資料,故PTX平臺會保留每台車輛最近2小時內的最新ㄧ筆資料,請加值業者再使用該項資料時特別注意。

    備註:系統持續更新,整體只會有最新兩小時內的資料

  • 公路總局及代管縣市之公車預估到站N1資料使用提醒:

    目前公總系統之公車預估到站N1資料,原則每1分鐘更新一次,PTX平臺會即時更新並保留每條路線站牌上最新一筆預估到站資訊,惟考量有時來源端資料因故未及時更新、來源端網路中斷、與來源端網路間傳輸問題等,故PTX平臺會保留每條路線最近2小時內最新的預估到站資料,請加值業者再使用該項資料時特別注意。

    備註:系統持續更新,整體只會有最新兩小時內的資料

  • 公車動態A1及A2相關狀態Status代碼意義補充說明:

    (1) DutyStatus('0:正常','1: 開始','2:結束'):0通常是車機剛開機才會顯示的值,表示車輛尚未正式發班;1是指一般車機處於行駛之狀態,表示車輛已開始執勤;2是車機行經公車路線之末端站位後,表示車輛已完成任務

    (2) BusStatus('99: 非營運狀態'):99通常為該車輛不提供服務或車內場站調度或去執行專車/加油..等任務才會切換的狀態,系統會伴隨DutyStatus = 2 (結束),公車動態系統不會預估該車輛之預估到站時間,以避免影響動態正確性。

results matching ""

    No results matching ""