應用程式介面規格

一個可以幫助您檢查有關「資料一線通」的學習教程和資料的地方

1. 歷史資料庫文件列表API

API端點 https://api.data.gov.hk/v1/historical-archive/list-files

HTTP請求方法: GET

取回在startend指定日期以內並符合categoryproviderformat參數的檔案清單。

每次最多有max數目的結果返回,首skip數目的結果會被略去。利用這兩個參數可達到分頁用途。

如果是一個成功的呼叫,JSON格式的檔案清單和結果總計將會隨著狀態碼 200 返回。
如果請求含有語法錯誤例如缺少必要的參數,JSON格式的錯誤清單將會隨著狀態碼 400 返回。

參數 描述 必要
start YYYYMMDD格式的開始日期(包括首日), 例如: 20160101。
end YYYYMMDD格式的結束日期(包括尾日), 例如: 20161231。
category 類別識別碼, 例如: information-technology-and-broadcasting
類別識別碼 的完整列表如下::
類別識別碼 類別描述
city-management城市管理
climate-and-weather氣象
commerce-and-industry工商業
development發展
education教育
employment-and-labour就業及勞工
environment環境
finance財經
food食物
health衞生
housing房屋
information-technology-and-broadcasting資訊科技及廣播
law-and-security法律及保安
population人口
recreation-and-culture康樂及文化
social-welfare社會福利
transport運輸
miscellaneous其他
provider 數據提供機構識別碼, 例如: hk-ogcio
數據提供機構識別碼 的完整列表如下::
數據提供機構識別碼 數據提供機構名稱
hk-afcd漁農自然護理署
hk-archsd建築署
hk-bd屋宇署
hk-cad民航處
hk-cedd土木工程拓展署
hk-censtatd政府統計處
hk-cr公司註冊處
hk-csd香港懲教署
hk-customs香港海關
hk-dh衞生署
hk-devb發展局
hk-edb教育局
hk-emsd機電工程署
hk-epd環境保護署
hk-effo效率促進辦公室
hk-fehd食物環境衞生署
hk-fso財政司司長辦公室
hk-fstb財經事務及庫務局
hk-gld政府物流服務署
hk-govtlab政府化驗所
hk-gpa政府產業署
hk-hko香港天文台
hk-hkpf香港警務處
hk-housing香港房屋委員會
hk-ipd知識產權署
hk-ird稅務局
hk-isd政府新聞處
hk-itc創新科技署
hk-landsd地政總署
hk-lcsd康樂及文化事務署
hk-lr土地註冊處
hk-md海事處
hk-ofca通訊事務管理局辦公室
hk-ofnaa電影、報刊及物品管理辦事處
hk-ogcio政府資訊科技總監辦公室
hk-oro破產管理署
hk-pland規劃署
hk-reo選舉事務處
hk-rthk香港電台
hk-rvd差餉物業估價署
hk-swd社會福利署
hk-td運輸署
hk-tid工業貿易署
hk-try庫務署
hk-ugc大學教育資助委員會秘書處
hk-wfsfaa在職家庭及學生資助事務處
centaline中原地產代理有限公司
clp中華電力有限公司
hkelectric香港電燈有限公司
mtr香港鐵路有限公司
rehabsociety香港復康會
hktramways香港電車有限公司
hkeaa香港考試及評核局
ia保險業監管局
hospital醫院管理局
starferry天星小輪有限公司
hkhs香港房屋協會
hkcert香港電腦保安事故協調中心
hk-ceo行政長官辦公室
hk-oci保險業監理處 (已解散)
format 檔案格式,以檔案的副檔名,例如: xls
search 關鍵詞搜尋。只有與數據集/資源名稱匹配的結果會返回。
order 排序。 有效選項為: dataset-endataset-tcdataset-scresource-enresource-tcresource-scurl。預設排序為url。.

-en/-tc/-sc 後綴表示用於排序的相應語言。

結果可以按如下排序:
  1. 數據集和資源名稱 - 如order是按dataset-endataset-tcdataset-sc
  2. 資源名稱 - 如order是按resource-en, resource-tc or resource-sc
  3. 網址 - 如order是按url
skip x個記錄會被省略。

2. 歷史存檔文件版本API

API端點 https://api.data.gov.hk/v1/historical-archive/list-file-versions

HTTP請求方法: GET

取回在日期(startend中提供)以內的檔案(url中提供)的歷史版本清單。
只有首10,000個結果將會返回。

如果是一個成功的呼叫,JSON格式的歷史版本時間戳清單,結果總計和字節總大小將會隨著狀態碼 200 返回。
如果請求含有語法錯誤例如缺少必要的參數,JSON格式的錯誤清單將會隨著狀態碼 400 返回。

參數 描述 必要
url 檔案網址,網址可從歷史檔案文件列表應用程式介面結果中找到。
start YYYYMMDD格式的開始日期(包括首日), 例如: 20160101。
end YYYYMMDD格式的結束日期(包括尾日), 例如: 20161231。

3. 歷史存檔文件下載API

API端點 https://api.data.gov.hk/v1/historical-archive/get-file

HTTP請求方法: GET

取回基於time的檔案(url中提供)歷史版本。

如果是一個成功的呼叫,狀態碼 302 將會返回, 請求者需要跟隨重定向然後接收狀態碼 200 和檔案。
如果請求含有語法錯誤例如缺少必要的參數,JSON格式的錯誤清單將會隨著狀態碼 400 返回。
如果請求的歷史版本檔案不存在,JSON格式的錯誤清單將會隨著狀態碼 404 返回。

參數 描述 必要
url 檔案網址,網址可從歷史檔案文件列表應用程式介面結果中找到。
time YYYYMMDD格式的存檔日期和時間, 例如: 20160101-0000
補充資訊:
  • 所有時間均以GMT + 8時區為準。
  • 最新的歷史數據來自昨天。

4. 歷史存檔模式下載API

API端點 https://api.data.gov.hk/v1/historical-archive/get-schema

HTTP請求方法: GET

取回基於date的模式(url中提供)歷史版本。

如果是一個成功的呼叫,狀態碼 302 將會返回, 請求者需要跟隨重定向然後接收狀態碼 200 和檔案。
如果請求含有語法錯誤例如缺少必要的參數,JSON格式的錯誤清單將會隨著狀態碼 400 返回。
如果請求的歷史版本檔案不存在,JSON格式的錯誤清單將會隨著狀態碼 404 返回。

參數 描述 必要
url 數據集的網址
date YYYYMMDD格式的日期, 例如: 20160101

5. 歷史存檔數據字典API

API端點 https://api.data.gov.hk/v1/historical-archive/get-data-dictionary

HTTP請求方法: GET

取回基於date的數據字典(url中提供)歷史版本。

如果是一個成功的呼叫,狀態碼 302 將會返回, 請求者需要跟隨重定向然後接收狀態碼 200 和檔案。
如果請求含有語法錯誤例如缺少必要的參數,JSON格式的錯誤清單將會隨著狀態碼 400 返回。
如果請求的歷史版本檔案不存在,JSON格式的錯誤清單將會隨著狀態碼 404 返回。

參數 描述 必要
url 數據集的網址
date YYYYMMDD格式的日期, 例如: 20160101

例子:
F101 按年齡、年及性別劃分的常住居民(英文)

F101 按年齡、年及性別劃分的常住居民
URL: http://www.bycensus2016.gov.hk/Page/Maintables/source/eng/F101/Result.xlsx

API端點 https://api.data.gov.hk/v1/filter

本應用程式介面接受查詢字串輸入。

輸入

查詢字串輸入參數

名稱 值說明 必要?
q 網址編碼(URL-Encoded) JSON 物件字串
(有關詳細信息,請參閱以下描述)

給查詢字串參數 "q" 的 JSON 物件字串規格

成員/名字 JSON 數據類型 值說明 必要?
resource string URL資源. URL可以在本頁的頂部找到
section number

章節編號 (僅在"數據部分"可用時才需要)

  • 由1開始的正整數 (預設: 1)
filters array

篩選條件的數據陣列:

[ [F1], [F2], ..., [Fn] ]

F 為篩選條件。篩選條件數據陣列中每一個篩選條件皆為數據陣列,當中包含三個JSON元素,如下:

Fn = [ Cn, "OP", [ "O1", "O2", ..., "On" ] ]

Cn 為欄位編號(number)
OP 為篩選條件運算符(string),以下列表為目前所支持的篩選條件運算符:


  • eq - 等於
  • ne - 不等於
  • in - 在...之內 (只限文字)
  • ni - 不在...之內 (只限文字)
  • lt - 小於 (只限數字)
  • le - 小於或等於 (只限數字)
  • gt - 大於 (只限數字)
  • ge - 大於或等於 (只限數字)
  • bt - 在...之間 (只限數字)
  • ct - 包含 (只限文字)
  • nct - 不包含 (只限文字)
  • bw - 以...開始 (只限文字)
  • nbw - 不以...開始 (只限文字)
  • ew - 以...結束 (只限文字)
  • new - 不以...結束 (只限文字)

在 [ "O1", "O2", ..., "On" ] 數據陣列中,O (string) 為篩選條件操作數。

當篩選條件運算符 OP 為 bw(在...之間)時,必需提供兩個篩選條件操作數。

當篩選條件運算符 OP 為 in(在...之內) 或 ni(不在...之內)時,必需提供兩個或更多的篩選條件操作數。

其餘的篩選條件運算符只需提供一個篩選條件操作數。

sorts array

排序條件的數據陣列:

[ [S1], [S2], ..., [Sn] ]

S 為排序條件。排序條件數據陣列中每一個排序條件皆為數據陣列,當中包含兩個JSON元素,如下:

Sn = [ Cn, "ORDER" ]

Cn 為欄位編號(number)
ORDER 為排序條件(string), 以下為可選的排序條件值:

  • asc - 升序
  • desc - 降序
format string
輸出格式:

  • CSV (預設)
  • json
  • xml

例子

輸入

  • resource = 資源URL
  • section = 1,
  • 篩選條件及排序條件為:
    • 欄位編號 1 中,其值等於 “abc” 和,
    • 欄位編號 1 中,其值不等於 “xyz”和,
    • 欄位編號 3 ,排序為升序 和,
    • 欄位編號 4 ,排序為降序
  • format(輸出格式)= JSON,

JSON 物件

{
	"resource": "https://api.data.gov.hk/v1/filter",
	"section":1,
	"format":"json",
	"filter": [
		[1, "eq", ["abc"]],
		[1, "ne", ["xyx"]]
	],
	"sorts: [
		[3, "asc"],
		[4, "desc"]
	]
}
							

輸出 [JSON 物件]

根據"format"參數的CSV、JSON或XML檔案 以上為 JSON 物件字串

例子:
最近的學校

查找距離最近的學校(緯度和經度)
使用的數據集: 學校位置及資料

API端點 https://api.data.gov.hk/v1/nearest-schools

本應用程式介面接受查詢字串輸入。

Input

查詢字串輸入參數

輸入
lat: 查詢地點之緯度(WGS84)
long: 查詢地點之經度(WGS84)
max: 限制回覆結果的數目(預設:全部,上限:100)
 
輸出
[JSON格式]
results: 以與查詢地點距離順序排列的結果
注意:
本應用程式介面(介面)由「資料一線通」團隊開發,旨在為軟件及應用程式開發商提供使用原始數據集的不同角度和方法。經由本介面產生的數據子集,或未載有原始數據集內由數據提供者提供的全部資料。使用本介面時,務須參考原始數據集,以掌握全面資料。