-
Notifications
You must be signed in to change notification settings - Fork 1
/
共通性資料存取 應用程式介面(API)規範.yaml
418 lines (384 loc) · 17.2 KB
/
共通性資料存取 應用程式介面(API)規範.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
swagger: '2.0'
info:
version: "1.0"
title: 共通性資料存取應用程式介面規範
description: 目的，應用範圍，名詞定義等請參照此[pdf檔案](http://file.data.gov.tw/opendatafile/%E5%85%B1%E9%80%9A%E6%80%A7%E8%B3%87%E6%96%99%E5%AD%98%E5%8F%96%E6%87%89%E7%94%A8%E7%A8%8B%E5%BC%8F%E4%BB%8B%E9%9D%A2API%E8%A6%8F%E7%AF%84.pdf)。
# host: data.gov.tw
basePath: /api/v1
produces:
- application/json
- application/x-gzip
paths:
/rest/group:
get:
operationId: listGroup
produces:
- application/json
tags:
- 資料集詮釋資料 API
description: |
取得分類群組清單。
* 分類編號(categoryCode)為政府入口網之服務分類編號 3 碼 18 類。
* 輸出範例之分類編號等於資料集詮釋資料之分類編號。
parameters:
- $ref: '#/parameters/limitParam'
- $ref: '#/parameters/offsetParam'
responses:
200:
description: |
回傳資料開放平臺上所有資料集之分類編號(categoryCode)。
schema:
type: object
properties:
success:
type: boolean
description: 表示回傳是否成功。
result:
type: array
items:
type: string
description: 分類編號(categoryCode)
examples:
application/json: {"success": true, "result":["100","A00"]}
### Wrong return value with data.gov.tw implementation
/rest/group/{categoryCode}:
get:
operationId: getDatasetIdInGroup
produces:
- application/json
tags:
- 資料集詮釋資料 API
description: |
取得群組相關之資料集編號。
* 分類編號(categoryCode)為政府入口網之服務分類編號 3 碼 18 類。
* 此資源路徑 categoryCode 等於資料集詮釋資料之分類編號。
* categoryCode 可由「取得分類群組清單」API 項目取得。
* 輸出範例之資料集編號等於資料集詮釋資料之資料集編號。
parameters:
- name: categoryCode
in: path
description: 分類編號，如：E00
required: true
type: string
responses:
200:
description:
回傳群組相關之資料集編號。
schema:
type: object
properties:
success:
type: boolean
description: 表示回傳是否成功。
result:
type: object
properties:
categoryCode:
type: string
description: 群組分類編號。
display_name:
type: string
description: 群組分類名稱，可使用中文。
description:
type: string
description: 群組分類描述。
package_count:
type: integer
description: 群組內資料集數量。
created:
type: string
description: 建立日期。
packages:
type: array
description: 群組內資料集編號清單。
items:
type: string
examples:
application/json:
{"success": true, "result": {"categoryCode": "E00","display_name": "生活安全及品質","description": "E00 類別","package_count": 2,"created": "2014-05-14 17:26:56","packages": [ "A41000000G-000004", "301000000A-123456"]}}
/rest/tag:
get:
operationId: listTag
produces:
- application/json
tags:
- 資料集詮釋資料 API
description:
取得標籤清單。
parameters:
- $ref: '#/parameters/limitParam'
- $ref: '#/parameters/offsetParam'
responses:
200:
description: |
資料開放平臺上所有資料集之標籤清單。標籤(tag)為各機關紀錄於資料集詮釋資料中之標籤/關鍵字(keyword)。若查無資料則回傳空陣列。
schema:
type: object
properties:
success:
type: boolean
description: 表示回傳是否成功。
result:
type: array
items:
type: string
examples:
application/json: {"success":true,"result":["tag1","tag2"]}
/rest/tag/{tagName}:
get:
operationId: getDatasetIdOfTag
produces:
- application/json
tags:
- 資料集詮釋資料 API
description:
取得標籤相關之資料集編號。
* 輸出內容之資料集編號(identifier) 係為資料集之資訊辨識編碼。資料集編號可由平臺資料集編號清單或資料集詮釋資料描述取得。
* 標籤(tag)為各機關紀錄於資料集詮釋資料中的標籤/關鍵字(keyword)。
* tagName 可由「取得標籤清單」API 項目取得。
parameters:
- name: tagName
in: path
description: 標籤，如：水情
required: true
type: string
responses:
200:
description:
資料開放平臺上所有具該標籤的資料集之資料集編號。若查無資料則回傳空陣列。
schema:
type: object
properties:
success:
type: boolean
description: 表示回傳是否成功。
result:
type: array
description: 標籤相關之資料集編號(identifier)
items:
type: string
examples:
application/json: {"success":true, "result":[ "A41000000G-000004","301000000A-123456","355000000I-000003","355000000I-000004","301000000A-000005" ]}
/rest/dataset:
get:
operationId: listDatasetId
produces:
- application/json
tags:
- 資料集詮釋資料 API
description: |
取得資料集編號清單。
* 輸出內容之資料集編號(identifier)係為資料集之資訊辨識編碼。
* 輸出內容之資料集編號等於資料集詮釋資料之資料集編號。
parameters:
- name: modified
in: query
description: |
日期, 詮釋資料最後更新時間大於或等於輸入之查詢條件。若無輸入，則傳回所有資料集編號清單。
日期格式為 RFC3339 date-time。
required: false
type: string
format: date-time
- $ref: '#/parameters/limitParam'
- $ref: '#/parameters/offsetParam'
responses:
200:
description:
資料開放平臺所有資料集之資料集編號。若查無資料則回傳空陣列。
schema:
type: object
properties:
success:
type: boolean
description: 表示回傳是否成功。
result:
type: array
items:
type: string
examples:
application/json: {"success":true, "result":["A41000000G-000004","301000000A-123456","355000000I-000003","355000000-000004","301000000A-000005"]}
/rest/dataset/{identifier}:
get:
operationId: getDatasetById
produces:
- application/json
tags:
- 資料集詮釋資料 API
description: |
取得資料集詮釋資料。
* 資料集編號(identifier)係為資料集之資訊辨識編碼。等於資料集詮釋資料的資料集編號。
* 資源路徑之資料集編號可由「取得資料集標號清單」、「取得群組相關的資料集編號」、「取得標籤相關的資料集編號」等 API 項目取得。
* 若不輸入{identifier}參數，則請詳見「取得資料集編號清單」說明。
parameters:
- name: identifier
in: path
description: 資料集編號，如：A41000000G-000001
required: true
type: string
responses:
200:
description: |
* 資料開放平臺提供之資料集詮釋資料欄位及內容。詮釋資料欄位為「資料集詮釋資料標準規範」制定之詮釋資料欄位或機關自行定義之詮釋資料欄位。
* 當執行跨平臺詮釋資料交換時，輸出內容必須包含機關 OID(publisherOID)與機關代號(publisherOrgCode)，以利各資料開放平臺識別資料集來源。機關 OID 與機關代號欄位內容，請參見政府物件識別碼網站(http://oid.nat.gov.tw/OIDWeb/chmain.html)。
schema:
type: object
properties:
success:
type: boolean
description: 表示回傳是否成功。
result:
type: object
examples:
application/json:
{"success": true, "result":{ "categoryCode":"I00", "identifier":"A41000000G-000001", "title":"行政院公報", "description":"行政院及所屬機關涉及人民權益之法 令等重要事項，主要內容有法規、行 政規則、公告及送達、處分、特載 （總統文告及院長談話）、轉載（經 總統公布之條約、法律、緊急命 令）、專載（院會院長提示、決定、 決議事項）及其他等 8 大類。", "fieldDescription":"公報類型、編輯分類(篇名)、公 告機關、承辦機關、發文日期、發文 字號、標題、英文標題、主旨、依 據、關鍵字、英文關鍵字、公告事 項、表示意見截止日、內容主題、施 政分類、服務分類、附件個數、內容 網頁連結、英文網址連結。", "type":"rawData", "license":"政府資料開放平臺資料使用規範", "licenseURL":"http://data.gov.tw/principle", "cost":"免費", "costURL":"", "costLaw":"", "organization":"國家發展委員會", "organizationContactName":"郭大明 先生", "organizationContactPhone":"02-23165300#XX", "organizationContactEmail":"[email protected] ", "publisher":"國家發展委員會", "publisherContactName":"鄭大明 先生", "publisherContactPhone":"02-23165300#OO ", "publisherContactEmail":"[email protected]", "publisherOID":"2.16.886.101.20003.20069", "publisherOrgCode":"A41000000G", "accrualPeriodicity":"每日", "temporalCoverageFrom":"2014-01-01", "temporalCoverageTo":"2015-01-01", "issued":"2015-01-01 23:59:59", "modified":"2015-01-01 23:59:59", "spatial":"臺灣", "language":"zh", "landingPage":"http://gazette.nat.gov.tw/egFront/Open Data/list.jsp", "keyword":[ "公報", "施政", "服務", "行政院" ], "numberOfData":4600, "notes":"正式出版後時有異動，請以正式出版之書 目資料為準。API 參數：year 代表年度", "distribution": [ { "resourceID":"A41000000G-000001-001", "resourceDescription":"行政院公報-民國 103 年-交通建設篇- XML", "format":"XML", "resourceModified":"2015-01-01 23:59:59", "downloadURL":"http://gazette.nat.gov.tw/eg Front/OpenData/download.jsp", "metadataSourceOfData":"http://example1", "characterSetCode":"UTF-8" }, { "resourceID":"A41000000G-000001-002", "resourceDescription":"行政院公報-民國 103 年-衛生勞動篇- ZIP", "format":"ZIP", "resourceModified":"2015-01-01 23:59:59", "downloadURL":"http://oid.nat.gov.tw/OID Web/GDS.zip", "metadataSourceOfData":"http://example2", "characterSetCode":"BIG-5" } , { "resourceID":"A41000000G-000001-003", "resourceDescription":"行政院公報-民國 103 年-教育文化篇- services", "format":"services", "resourceModified":"2015-01-01 23:59:59", "accessURL":"http://example/endpoint", "metadataSourceOfData":"http://example3", "characterSetCode":"UTF-8" } ] } }
/rest/datastore/{resourceID}:
get:
operationId: getDataBySetId
produces:
- application/json
tags:
- 資料資源內容API
description:
取得資料集之資料資源內容。
parameters:
- name: resourceID
required: true
in: path
type: string
description: 資料資源編號。
- name: filters
required: false
in: query
type: string
description: |
輸入資料資源之過濾條件，參數為資料英文欄位所含之內容。
正確範例：filters={"EngFiled1":"ValueaA","EngFiled2":"ValueB"}
錯誤範例：filters=EngFiled1:ValueaA 或filters="EngFiled1":"ValueA"
- name: q
required: false
in: query
type: string
description: |
資料資源所有內容之全文檢索字串。視業務需要可選擇性提供。
正確範例：q=臺北市
錯誤範例：q=市（關鍵字太短）
- name: sort
required: false
in: query
type: string
description: |
排序資料資源之欄位名稱。只能指定一個。
- $ref: '#/parameters/limitParam'
- $ref: '#/parameters/offsetParam'
- name: fields
required: true
in: query
type: string
description: 資料資源之欄位名稱，將回傳指定欄位的內容。指定複數欄位時以逗號(,)隔開。
responses:
200:
description: |
輸出資訊包含資料集欄位內容，將先呈現欄位格式，再回傳資料內容。
成功時回傳不含 error 欄位，失敗時回傳不含 result 欄位。
schema:
type: object
properties:
success:
type: boolean
description: 表示回傳是否成功。
result:
$ref: '#/definitions/DataStoreResult'
error:
$ref: '#/definitions/DataStoreError'
/dump/datastore/{resourceID}:
get:
operationId: dumpDataBySetId
produces:
- application/x-gzip
tags:
- 資料資源內容API
description:
下載資料集之資料資源全部內容。
parameters:
- name: resourceID
required: true
in: path
type: string
description: 資料資源編號。
- name: format
required: true
in: query
type: string
description: 資料資源回傳之內容格式，可為 json, csv, xml 其中之一。
enum: ['json', 'csv', 'xml']
responses:
200:
description:
以指定格式提供資料集之資料資源全部內容，以 zip 檔案輸出。
schema:
type: file
parameters:
limitParam:
name: limit
in: query
description: 限制最多回傳的資料筆數。
required: false
type: integer
offsetParam:
name: offset
in: query
description: 指定從第幾筆後開始回傳。可與 limit 配合使用達到分頁目的。
required: false
type: integer
definitions:
DataStoreResult:
type: object
description: 表示回傳成功之內容。
properties:
resource_id:
type: string
fields:
type: array
items:
type: object
properties:
id:
type: string
description: field 名稱
type:
type: string
description: field 的 json 資料型態
records:
type: array
description:
回傳之資料內容列表，資料內容包含欄位名稱及欄位值；欄位名稱與 fields 回傳的名稱相同，但順序可不同。
items:
type: object
limit:
type: integer
description: 限制最多回傳之資料筆數。
offset:
type: integer
description: 為從第幾筆之後開始回傳。
total:
type: integer
description: 全部資料筆數。
DataStoreError:
type: object
description: |
表示回傳失敗之資訊內容。
properties:
message:
type: string
description: 錯誤訊息。
type:
type: string
description: |
| 錯誤代碼 | 訊息內容 | 說明 |
|----------|----------|----------|
| ER0100 | 找不到Resource 資料。| 找不到指定的 resourceID資料內容。|
| ER0200 | 輸入的參數名稱錯誤。| 輸入的參數名稱不在規範中。|
| ER0210 | 輸入的參數內容格式錯誤。|輸入的參數內容格式有錯誤，例如 limit=11.5 或offset=all。|
| ER0220 | 輸入的參數內容中，欄位名稱不存在。|在輸入參數 filters、sort、fields 的內容中，所指定欄位名稱不存在。|
| ER0500 | 系統錯誤。| 其他系統錯誤。|
錯誤類別。回傳錯誤代碼如上表，錯誤代碼為ER 開頭，加上 4 位數字，錯誤內容詳細描述方式由系統自行定義。亦可自行定義詳細之錯誤代碼，於原代碼後增加自行定義位數，錯誤代碼不超過 10 個字元。如輸入的參數內容格式錯誤代碼為ER0210，可再細分為內容未輸入 ER021001、內容過長 ER021002 等。