Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?

本文件主要係提供使用公共運輸整合流通服務平臺(Public Transport Data eXchange)各項資料服務加值業者,在程式開發過程中常見問題的處理方式及資料使用的注意事項,使開發者能更快速地掌握PTX APIs的資料特性,並避免在旅運加值應用上資料運用錯誤。

【平臺使用會員分級說明】

交通部公共運輸整合資訊流通服務平臺會員將分為網站會員及API會員,API會員將細分為一般會員進階會員專案用戶;請詳見下列會員權益說明

更多申請會員FAQ請參閱連結

PTX平臺導入API機制及會員申請流程說明,可下載文件參閱連結


【資料使用注意事項】

  • 能否允許在APP端直接呼叫使用PTX APIs?

    PTX平台屬於開放資料平台,為避免網路頻寬及伺服器資源遭特定服務濫用,加值業者務必自建後台,另申請介接方式時將會針對不同用戶綁定每日呼叫次數限制,故使用者請依自身身份申請適合的會員用戶類型。

  • PTX API的網際網路資源統一資源識別元(URI)是否有規則?

    PTX API的URI有一定的命名原則(Naming Convention),詳細請參閱「PTX API URI Convention說明文件」

  • 對於檔案較大的靜態資料服務,建議介接方式?

    建議一、

    整批靜態資料下載因資料量較大,請勿直接取用,建議善用OData Select語法,篩檢所需之資料欄位可大量減少資料量。另若要用OData語法中的top跟skip來批次存取資料時,建議先針對整批靜態資料的主鍵值(PK)進行排序,再進行批次抓取。

    範例如下:介接國內定期班表資料 Key值欄位:FlightNumber, ScheduleStartDate

    建議二、

    對於取用大量資料的需求者,避免直接使用瀏覽器下載,以防止發生因瀏覽器session timeout而導致誤認PTX平台服務出現問題,建議可利用相關程式(如curl指令)將資料直接抓回使用。

  • 疑義資料處理程序?

    PTX平台係與各資料來源端協作模式,進行M2M資料介接,故若有任何資料面議題,平台會協助將問題反映給來源單位,請其協助確認並修正,惟為加速問題釐清,建議將問題佐證畫面與資料併同問題一併提出。

  • 為何同一運具但不同單位所提供相同資料項(如:路線/站牌/動態資料..等),會出現有值的欄位項目不太一致的情況?

    PTX平台目前係以各運具單位可提供資料項目之最大集合來制訂國內的公共運輸旅運資料標準,惟目前多數單位尚未完全依據標準產製資料,而是由PTX平台代為轉成一致之標準格式,故常有加值業者反應如公車資料中為何某些欄位公總有但台北市沒有或台北市有但台南市沒有的狀況產生,故提醒加值者使用資料前必須注意各單位間資料之差異性。


資料服務版本說明

資料服務V1版及V2版差別說明

V1版

服務內容包含航空、臺鐵、高鐵、公總公路客運及六都市區公車動靜態資料服務共56筆,市區公車資料及公路客運資料並無做區隔,新北無A1、A2資料僅提供N1動態資料,台中與高雄無A2動態資料,台北市無附屬路線概念,後續並不做任何修改與調整。

V2版

多輸出相關欄位提供較充分資料內容,便利開發人員直接使用,而不需再與其他API服務做串連間接取得(例如:不單僅輸出StaionID,同時也輸出StationName)。除提供既有V1版的資料服務項目外,105年度陸續擴充全台市區公車(CityBus)、公路客運(InterCityBus)動靜態資料、航空動靜態資料(含航班角度FIDS及機場角度FIDS)、台鐵動靜態資料項、高鐵動靜態資料項、自行車動靜態資料項、應用服務動靜態資料,106年擴充捷運動靜態資料項、航空新增國內/國際定期時刻表資料項、高鐵新增最新消息資料項,累計服務共達258項。未來,陸續也將會持續新增服務。


API 認證授權機制

  1. 說明:本平臺原採用ticket認證授權機制,後配合API Management解決方案的導入,改採HMAC認證授權機制。

  2. 原ticket機制:係透過/v2/Account/Login API取得ticket,再透過該ticket取得各式API資料。該機制將配合新的HMAC機制導入後,隨即失效。

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

  4. 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分鐘

  1. HMAC認證失效樣態:依照存取API 的HTTP header資訊判別用戶是否為授權身份,若未符合身份驗證將以下列訊息回應用戶端。

    • 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 (未帶簽章,未經授權)

  2. Ticket與HMAC機制平行運轉期間,使用HMAC機制(APP ID及APP Key)則不須再取得ticket。

  3. APP ID及APP Key:不同層級的資料服務類型,會給予不同的ID/Key組合,例如:基礎資料服務(L1)與基礎加值服務(L2)會分別給予兩組不同的ID/Key組合(詳請參考資料服務查詢中的API服務類型,目前提供的資料服務多屬L1,L2之服務目前僅有場站空氣品質服務,後續會再進行擴充。

  4. 使用程式(如:C#、Java、JavaScript等)取得資料時,請記得加入HTTP Header設定(Accept-Encoding: gzip, deflate),可有效減傳輸量。

  5. 參考資料:

   - 範例程式碼 https://github.com/ptxmotc/Sample-code


航空API動靜態資料

  1. 介接航空資料時須注意本平臺機場代碼皆以IATA國際代碼三碼為API服務查詢及資料串接之基礎。
  2. 即時航班到離站資料(FIDS)分別以機場角度(Airport)及航班(Flight)角度提供資料服務,加值業者在使用時需注意應用面向避免引用錯誤。
  • 機場角度航班到離站資訊顯示(FIDSAirport):以第三方機場角度提供動態站別航班顯示資料。
  • 班機角度航班到離站資訊顯示(FIDSFlight):以飛機角度提供動態站別航班顯示資料。
  1. 航空定期航班班表由民航局及桃園機場提供,目前僅提供客運航班班表資料,國際定期航班班表有包含兩岸航班。
  2. 國際定期航班起飛或降落時間有+1的現象,代表Flight Date 日期+1天,並非+1小時,因航班日期皆以起飛城市當地時間及降落城市當地時間提供,為了解決班機所遇到之時差問題,如台北飛洛杉磯可能10月07日10:00早上台北起飛,10月07日07:00早上洛杉磯降落,此時航班僅會以10:00標示顯示;但若遇到台北飛孟買,10月09日1:00下午台北起飛,10月10日1:00早上孟買降落,此時就會顯示+1(天)
  3. 部分欄位若為空值是因來源單位尚未提供介接。
  4. 本平臺服務係針對全台航空資訊為主,故以機場為角度(FIDSAirport)之即時航班資料僅顯示國內機場;而班機為角度(FIDSFlight)之即時航班資料僅顯示國內機場的各班機出發(Departure)或抵達相關資訊(Arrival),如BR108班機由高雄飛往東京,則FIDSFlight即時航班資訊僅會顯示ScheduleDepartureTime、ActualDepartureTime及EstimatedDepartureTime,而BR108抵達相關資訊則無提供。

市區公車及公路客運API動靜態資料

  1. 動態資料傳遞延遲

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

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

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

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

※台中市與高雄市延遲較長是因為來源端本身有作Cache機制,故即使PTX每6秒Polling跟來源端Polling更新一次,仍無法即時更新資料。

  1. 動態資料更新時間資料說明
  更新時間項目       中文名稱說明   發生時間 範例
  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. 站牌與站位兩者間之差異

    (1) 站牌:一站牌點位若有多條公車路線行經,而各個公車路線擁有各自站牌桿時,就會有多筆站牌資料。

    (2) 站位:當多筆站牌資料表示為同一站牌區位時則以站位資料為表示,而站牌與站位間之關聯記錄在站牌基本資料中會有一個站位代碼StationID代表。

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

   站牌站位示意圖

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

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

  2. 公路客運路線ID的編碼原則

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

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

  4. 新北市【NewTaipei】來源

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

  5. 公路總局由原先需自行倒數的「UDP推播」改為「TCP推播」

    來源端將自動扣除公車預估到站秒數,定期每1分鐘計算更新一次,並提供最新更新時間及預估到站秒數,加值業者仍需注意N1資料更新後介接端在下一次更新前的延遲時間。

  6. 公路客運及公總代管的縣市N1訊息中雖沒有提供路線第1站之下一班車時刻資訊,但可從靜態資料的時刻表與動態GPS點位資料做關連加值,例如:當車子已經駛離起始站後,N1中的第1站預估到站就可以換成顯示下一班的時刻資訊。

  7. 公路路線ID編碼與實際站牌上顯示路線編號可能會有不一致的情況,如1659路線為例:當時此路線建置時,因共有3條主支線,該路線實際站牌資訊以1659A、1659B、1659C表達;然而在公路總局內部管理使用則以主支線方式1659、1659A 、 1659B做為區別,故建議參考公路客運i_Bus中,以桃園市八德區→國道3號→新北市土城區[經建國路]、[經介壽路]、[大湳至土城班次]呈現路線名稱為宜 ,提醒各加值業者在使用上必須注意。

  8. 公車N1資料經確認過班表資料後,若發現某些路線似乎沒有公車時刻的資料原因主要有兩者

    (1) 司機車機系統未開啟

    (2) 當下若非路線營運時間,就無預估到站資料。如公總8232A2路線為例:班表顯示周一至五都有營運,但查詢A1及N1資料時皆無8232A2資料,因為此路線一天只有一班,營運時間僅為06:10,故當您搜尋時間非此時間附近,就無此筆資料。

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

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

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

    (1) 路線站序(StopOfRoute)資料是用來儲存每條路線/附屬路線實際跑法的站序資料。

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

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

    (3) 當某特定路線下不存在任何其他附屬路線時,其路線站序(StopOfRoute)資料內容會完全等同於顯示用路線站序(DisplayStopOfRoute)資料。

    (4) 以前顯示用路線站序(DisplayStopOfRoute)是併同在路線站序(StopOfRoute)資料中,並以KeyPattern欄位進行區分,但由於多數加值業者反應將此兩項資料加以區分以利使用,因此針對部分縣市(如台北市及新北市)新增提供顯示用路線站序(DisplayStopOfRoute)資料,並將原路線站序(StopOfRoute)中的KeyPattern欄位刪除及將相對應的資料搬移至顯示用路線站序(DisplayStopOfRoute)資料中。

  11. 為何預估到站資料(N1)有些有車牌號碼有些沒有?而有時候該值為負值?

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

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

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

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

  13. 公車時刻表資料:

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

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

  15. 起迄站中英文名稱:

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

  16. 站牌點位資料品質:

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

  17. 路線資料內HasSubRoute欄位說明:

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

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

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

    a. 同公總APP顯示方式,使用「末班資訊」文字,取代「末班車已過」。
    b. 為APP新增額外判斷程式,該判斷邏輯為:若EstimateTime欄位為NULL且欄位isLastBus=0,則顯示「末班資訊」。
    c. 當使用者點選「末班資訊」,可顯示下列文字「末班車資訊請電洽: XX客運, 電話: XX-XXXXXXXX」。

  19. 公路總局及代管縣市之預估到站N1資料DataTime與SrcTransTime欄位補充說明:

    (1) 公總N1資料現在是「固定一分鐘傳送一次全部路線的N1」到PTX平台, 傳送方式採TCP協定拆分成多數個封包連續不斷推播進PTX平台,原則上, SrcTransTime一樣, 就表示屬於同一批全部路線N1資料的傳送, 但因為資料很多,一秒沒辦法全部送完,所以可能不會全部訊息的SrcTransTime都完全一樣, 故可能會在幾秒的前後範圍內。
    (2) 資料傳送時間(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跟便民網頁就是一直顯示進站中。

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

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

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

    備註: (1) 系統持續更新,整體只會有最新兩小時內的資料 (2) 部分縣市因公車路線數量少、班次數少,故有時會發生A1資料中的SrcTransTime, 停留在30分或1個小時以前的資料, 使用時請注意

  21. 公路總局及代管縣市之公車動態定點A2資料使用提醒:

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

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

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

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

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

雙鐵API動靜態資料

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

  2. 雙鐵臨時加班資訊: 雙鐵僅提供前一天異動資訊,目前尚無法提供當日臨時加班資訊

  3. 「列車即時準點/誤點資料」與「車站別列車即時到離站電子看板資料」之差異:

    「列車即時準點/誤點資料」為台鐵提供的原始資料,由於該項資料當初僅提供[車次代碼]與[誤點時間]兩欄位,本平台為利各加值單位方便應用,透過台鐵提供的每日列車時刻表,轉換成每日站別時刻表,並將其與「列車即時準點/誤點資料」進行關聯,產製全台各車站之前後30分鐘之「車站別列車即時到離站電子看板資料」,由於本項資料為加值轉換所得,非由台鐵各車站直接介接取得,故請各位加值者審慎使用,或自行設計演算邏輯轉換處理。 另台鐵為提高前述轉換邏輯之準確性,已於「列車即時準點/誤點資料」中新增[最近停靠車站代碼]欄位,本平台後續會將此欄位納入轉換邏輯中,並將已通過各車站之車次資訊過濾,使「車站別列車即時到離站電子看板資料」更符合實際真實的狀況。

  4. 定期時刻表與每日時刻表之差異:

    為確保時刻表的正確性及即時性,台鐵提供近60天每日時刻表、高鐵提供近45天每日時刻表,然而考量國內外旅客對於在臺旅行常需在數個月前規劃行程,若超過此段期間之時刻表資料則可參考定期時刻表,提供未來數個月之後之旅運規劃服務(通常國外旅客來台觀光較需要使用定期時刻表資料)。

  5. 車站代碼(StationID)與車站簡碼(StationCode)之差異:

    StationID通常為列車排點系統的車站代碼系統,時刻表資料中即以此代碼為主;

    StationCode主要是票務系統如訂票系統用的車站簡碼,加值業者使用時必須先了解其差異與使用時機。

靜態資料差異化/異動檔API資料

  1. 主要係提供不同資料版本間,特定資料項目(如路線、站牌、路線站序、時刻表、票價、線型圖資..等)之異動檔資料查詢服務,期能讓加值業者快速瞭解哪些資料項目已異動需即時進行資料更新,並讓民眾可以獲得最新的公共運輸資訊。

  2. 近期異動資料查詢API內的VariationType欄位說明:為標示被比較的兩個版本資料的變化狀態(新增、修改、刪除)。

    但其中標示為「修改」狀態的資料實際上可能並無變化,而造成此情形的狀況可能如下(以三個版本的情況為例):

    (1) A→ B →A : 代表資料實際無異動

    (2) A → (已被刪除) →A :代表資料實際無異動

    上述兩種狀況都可以透過比對實際資料得之資料並無異動, 但由於考量到效能因素以及資料特性,資料此在短時間內並不會太常發生此狀況,因此本平台並不會針對各欄位細節進行比對確認是否真的有無異動。


【URI命名原則】

開放資料可透過URL方式取得資料。

Web API (application programming interface) 的表現方式,分為網站根目錄(App Root)、資源路徑(Resource Path)和查詢選項(Query Options)

  • 網站根目錄:應用服務的基本網址,主要組成為(Domain)網域名稱和(App)應用程式名稱,並且透過 HTTP 協定連結而形成服務的基本網址。

    Domain: ptx.transportdata.tw

    App : MOTC或PTX

  • 資源路徑:指定資源項目路徑名稱。

目錄結構 意義
Version(版本) 提供服務的版本號。目前提供 v1(第一版),若沒有輸入,則預設最新版本
Service(服務) 依據載具本身提供的服務,例如:鐵道:台鐵(TRA)、高鐵(THSRC),空運:航空(Aviation),道路:公車(Bus)等等。
Application(應用內容)) 根據每個服務而提不同的應用內容,例如:航空:航班資訊(FIDS)和機場資訊(Airport)等。
  • 查詢選項:指定欲取得資料的範圍或查詢的條件。

  • PTX API URI說明文件詳見連結請詳見連結


【ODATA使用說明】

  1. 基本查詢 http://ptx.transportdata.tw/MOTC/Rail/TRA/Station?$format={format}

    {format}為資料格式:json、xml、csv

    範例:火車車站基本資料http://ptx.transportdata.tw/MOTC/Rail/TRA/Station?$format=xml

  2. 進階查詢

    {dataId}:資料代號

    {format}:資料格式

    {top}:取最前筆數

    {skip}:跳過筆數

    {orderby}:排序欄位

    範例:火車車站資本資料

    http://ptx.transportdata.tw/MOTC/v2/Rail/TRA/Station?$orderby=StationID&$top=10&$skip=100&$format=JSON

    ps:其中StationID為資料欄位名稱

  3. ODATA服務開發實作請詳見連結


【API應用服務教學】

公共運輸整合資訊流通服務平臺提供結構化、多彈性、多種領域API服務,以下將教學使用者如何透過所申請的App ID及App Key存取Swagger資料。


更新時間:2018/04/12 12:07:00

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.