跳至主要內容

政府資料開放平臺

:::

附錄

附錄 1－OpenAPI Specification

JSON 格式－以「交通部運輸資料流通服務平臺」為例

該規範已建立符合 OpenAPI 3.0.1 規範之 JSON 格式說明文件 (網路位址) ，以下提供已轉換至 OAS3 之 JSON 與 YAML 格式比對摘要：

● OpenAPI 欄位：版本描述。
JSON 格式 YAML 格式
{
"openapi": "3.0.1",		 openapi: 3.0.1
● server 欄位：路徑描述。
JSON 格式 YAML 格式
"servers": [
{
"url":
"https://tdx.transportdata.tw/api/basic
"
}
],		 servers:
- url:
https://tdx.transportdata.tw/api/basic
● info 欄位：該 API 之基本詮釋資料。
JSON 格式 YAML 格式
"info": {
"title": "公共運輸-公車",
"description": "本平臺提供涵蓋全國尺度
之交通旅運資料服務 API，歡迎各產政學單位介接使
用。\n<br><span class=swagger
description-indicatation>利用本平臺開放資
料進行各項應用服務開發時，請考量不同特性使用者
(如：性別/身心障礙/老幼等)的需求，並歡迎回饋寶
貴意見。</span>\n---\n##### API 線上說明
(Swagger UI)使用流程與注意事項：\n1. 若不使
用 API 金鑰呼叫 API，則僅能透過瀏覽器呼叫`【基
礎】`服務 ，且每個呼叫來源端 IP 的上限為每日 50
次。\n2. `【進階】`、`【加值】`、`【歷史】`
、`【MaaS】`服務需加入會員並取得 API 金鑰之後
才能使用。\n3. 欲使用 API 金鑰呼叫 API，需[註
冊為 TDX 會員](/register)，並於會員中心取得
API 金鑰。\n4. 註冊為會員之後，至[【會員專區資料服務-服務金鑰】](/user/dataservice/key
)功能頁面，從預設金鑰(或建立新的金鑰)取得
Client Id 和 Client Secret 資訊。\n5. 點選
Swagger UI 上的 Authorize 按鈕，依指示填入
Client Id 和 Client Secret 資訊並進行驗證，
驗證完成後可開始於 Swagger UI 使用 API。\n6.
欲透過程式介接 API，可參考[範例程式]
(https://github.com/tdxmotc/SampleCode)
。\n7. 為確保系統資源使用的合理分配與避免遭受
濫用，於 Swagger UI 上使用 API 與程式介接 API
的行為將被記錄並定期做檢視。\n\n##### API 呼
叫次數限制:\n1. 若不使用 API 金鑰呼叫 API，則
僅能透過瀏覽器呼叫`【基礎】`服務 ，且每個呼叫
來源端 IP 的上限為每日 50 次。\n2. 使用 API 金鑰
呼叫 API，每個呼叫來源端 IP 呼叫次數限制為 50 次
/秒 (無每日上限)。\n\nAPI OAS 文本 :[請點我]
(https://tdx.transportdata.tw/backend/a
pi/File/Swagger/V3/2998e851-81d0-40f5-
b26d-77e2f5ac4118)",
"version": "v2"
},		 info:
title: 公共運輸-公車
description: >-
本平臺提供涵蓋全國尺度之交通旅運資料服務
API，歡迎各產政學單位介接使用。
<br><span class=swagger-description-
indicatation>利用本平臺開放資料進行各項應用
服務開發時，請考量不同特性使用者(如：性別/身心
障礙/老幼等)的需求，並歡迎回饋寶貴意見。
---
##### API 線上說明(Swagger UI)使用流程與注
意事項：
1. 若不使用 API 金鑰呼叫 API，則僅能透過瀏覽器
呼叫`【基礎】`服務 ，且每個呼叫來源端 IP 的上限
為每日 50 次。
2. `【進階】`、`【加值】`、`【歷史】`、`
【MaaS】`服務需加入會員並取得 API 金鑰之後才能
使用。
3. 欲使用 API 金鑰呼叫 API，需[註冊為 TDX 會員]
(/register)，並於會員中心取得 API 金鑰。
4.註冊為會員之後，至[【會員專區-資料服務-服務
金鑰】](/user/dataservice/key)功能頁面，從
預設金鑰(或建立新的金鑰)取得 Client Id 和
Client Secret 資訊。
5. 點選 Swagger UI 上的 Authorize 按鈕，依指
示填入 Client Id 和 Client Secret 資訊並進行
驗證，驗證完成後可開始於 Swagger UI 使用 API。
6. 欲透過程式介接 API，可參考[範例程式]
(https://github.com/tdxmotc/SampleCode)
。
7. 為確保系統資源使用的合理分配與避免遭受濫用
，於 Swagger UI 上使用 API 與程式介接 API 的行
為將被記錄並定期做檢視。
##### API 呼叫次數限制:
1. 若不使用 API 金鑰呼叫 API，則僅能透過瀏覽器
呼叫`【基礎】`服務 ，且每個呼叫來源端 IP 的上限
為每日 50 次。
2. 使用 API 金鑰呼叫 API，每個呼叫來源端 IP 呼
叫次數限制為 50 次/秒 (無每日上限)。
API OAS 文本
:[請點我](https://tdx.transportdata.tw/b
ackend/api/File/Swagger/V3/2998e851-
81d0-40f5-b26d-77e2f5ac4118)
version: v2
● paths 欄位：該 API 各項功能之呼叫路徑，可與 server 欄位中的路徑結合為完整網址，並提供該項 API 之各項欄位、類別定義，以及範例說明。
(本案例僅摘要「取得指定[縣市]的公車動態定時資料(A1)」功能)
JSON 格式 YAML 格式
"paths": {

"/v2/Bus/RealTimeByFrequency/Streaming/City
/{City}": {
"get": {
"tags": [
"CityBus"
],
"summary": "取得指定[縣市]的公車動態定
時資料(A1)[逐筆更新]",
"description": "### 市區公車之定時資料
(A1) ###\r\n- [逐筆更新]與[批次更新]之差異請詳見
資料使用葵花寶典([連結](https://ptxmotc.gitboo
ks.io/ptx-api-documentation/content/api-ziliao-shi-yong-zhu-yi-shi-xiang/
buslive.html))",
"operationId":
"CityBusApi_RealTimeByFrequency_UDP_2046",
"parameters": [
{
"name": "City",
"in": "path",
"description": "欲查詢縣市",
"required": true,
"schema": {
"enum": [
"Hsinchu",
"HsinchuCounty",
"MiaoliCounty",
"ChanghuaCounty",
"NantouCounty",
"YunlinCounty",
"ChiayiCounty",
"Chiayi",
"PingtungCounty",
"YilanCounty",
"HualienCounty",
"TaitungCounty",
"PenghuCounty",
"Keelung"
],
"type": "string"
},
"x-enum": {
"Keelung": "基隆市",
"YilanCounty": "宜蘭縣",
"ChiayiCounty": "嘉義縣",
"ChanghuaCounty": "彰化縣",
"HsinchuCounty": "新竹縣",
"MiaoliCounty": "苗栗縣",
"PenghuCounty": "澎湖縣",
"Hsinchu": "新竹市",
"PingtungCounty": "屏東縣",
"NantouCounty": "南投縣",
"HualienCounty": "花蓮縣",
"Chiayi": "嘉義市",
"TaitungCounty": "臺東縣",
"YunlinCounty": "雲林縣"
}
},
{
"name": "$select",
"in": "query",
"description": "挑選",
"schema": {
"type": "string"
}
},
{
"name": "$filter",
"in": "query",
"description": "過濾",
"schema": {
"type": "string"
}
},
{
"name": "$orderby",
"in": "query",
"description": "排序",
"schema": {
"type": "string"
}
},
{
"name": "$top",
"in": "query",
"description": "取前幾筆",
"schema": {
"type": "integer",
"default": 30
}
},
{
"name": "$skip",
"in": "query",
"description": "跳過前幾筆",
"schema": {
"type": "string"
}
},
{
"name": "health",
"in": "query",
"description": "加入參數'?
health=true'即可查詢此 API 服務的健康狀態",
"schema": {
"enum": [
"true",
"false"
],
"type": "string"
}
},
{
"name": "$format",
"in": "query",
"description": "指定來源格式",
"required": true,
"schema": {
"enum": [
"JSON",
"XML"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"title": "Array",
"type": "array",
"items": {
"$ref":
"#/components/schemas/PTX.Service.DTO.Bus.S
pecification.V2.BusA1Data"
}
}
},
"application/xml": {
"schema": {
"title": "Array",
"type": "array",
"items": {
"$ref":
"#/components/schemas/PTX.Service.DTO.Bus.S
pecification.V2.BusA1Data"
}
}
}
}
},
"304": {
"description": "服務端會在
Response 加上 Last-Modified header，表示最近的
更新時間。客戶端能利用此時間，於 Request 加上 IfModified-Since header，若沒有更新，服務端會回應
304 StatusCode 且空值 Content",
"content": {
"application/json": { },
"application/xml": { }
}
},
"299": {
"description": "加入參數'?
health=true'即可查詢此 API 服務的健康狀態",
"content": {
"application/json": {
"schema": {
"$ref":
"#/components/schemas/PTX.Service.DTO.Share
d.Specification.V3.Base.DisplayHealth"
}
},
"application/xml": {
"schema": {
"$ref":
"#/components/schemas/PTX.Service.DTO.Share
d.Specification.V3.Base.DisplayHealth"
}
}
}
}
}
}
},
paths:

/v2/Bus/RealTimeByFrequency/Streami
ng/City/{City}:
get:
tags:
- CityBus
summary: 取得指定[縣市]的公車動態
定時資料(A1)[逐筆更新]
description: "### 市區公車之定
時資料(A1) ###\r\n- [逐筆更新]與[批次更
新]之差異請詳見資料使用葵花寶典([連結]
(https://ptxmotc.gitbooks.io/ptxapi-documentation/content/api-ziliao-shi-yong-zhu-yi-shi-xiang/
buslive.html))"
operationId:
CityBusApi_RealTimeByFrequency_UDP_2046
parameters:
- name: City
in: path
description: 欲查詢縣市
required: true
schema:
enum:
- Hsinchu
- HsinchuCounty
- MiaoliCounty
- ChanghuaCounty
- NantouCounty
- YunlinCounty
- ChiayiCounty
- Chiayi
- PingtungCounty
- YilanCounty
- HualienCounty
- TaitungCounty
- PenghuCounty
- Keelung
type: string
x-enum:
Keelung: 基隆市
YilanCounty: 宜蘭縣
ChiayiCounty: 嘉義縣
ChanghuaCounty: 彰化縣
HsinchuCounty: 新竹縣
MiaoliCounty: 苗栗縣
PenghuCounty: 澎湖縣
Hsinchu: 新竹市
PingtungCounty: 屏東縣
NantouCounty: 南投縣
HualienCounty: 花蓮縣
Chiayi: 嘉義市
TaitungCounty: 臺東縣
YunlinCounty: 雲林縣
- name: $select
in: query
description: 挑選
schema:
type: string
- name: $filter
in: query
description: 過濾
schema:
type: string
- name: $orderby
in: query
description: 排序
schema:
type: string
- name: $top
in: query
description: 取前幾筆
schema:
type: integer
default: 30
- name: $skip
in: query
description: 跳過前幾筆
schema:
type: string
- name: health
in: query
description: 加入參數'?
health=true'即可查詢此 API 服務的健康狀
態
schema:
enum:
- 'true'
- 'false'
type: string
- name: $format
in: query
description: 指定來源格式
required: true
schema:
enum:
- JSON
- XML
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
title: Array
type: array
items:
$ref: >-
#/components/schemas/PTX.Service.DT
O.Bus.Specification.V2.BusA1Data
application/xml:
schema:
title: Array
type: array
items:
$ref: >-

#/components/schemas/PTX.Service.DT
O.Bus.Specification.V2.BusA1Data
'299':
description: 加入參數'?
health=true'即可查詢此 API 服務的健康狀
態
content:
application/json:
schema:
$ref: >-
#/components/schemas/PTX.Service.DT
O.Shared.Specification.V3.Base.Disp
layHealth
application/xml:
schema:
$ref: >-
#/components/schemas/PTX.Service.DT
O.Shared.Specification.V3.Base.Disp
layHealth
'304':
description: >-
服務端會在 Response 加上
Last-Modified
header，表示最近的更新時間
。客戶端能利用此時間，於 Request 加上 IfModified-Since
header，若沒有更新，服務端
會回應 304 StatusCode 且空值 Content
content:
application/json: {}
application/xml: {}

附錄 2－相關網站連結

1.OpenAPI Specification

這是測試站！ This is staging.