應用程式介面規範

應用程式介面規格

一個可以幫助您檢查有關「開放數據平台」的學習教程和資料的地方

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

API端點

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

HTTP請求方法： GET
取回在start和end指定日期以內並符合category，provider和 format參數的檔案清單。

每次最多有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	法律及保安
legislature	選舉及立法機關
miscellaneous	其他
population	人口
recreation-and-culture	康樂、體育及文化
social-welfare	社區及社會福利
transport	運輸

否

provider

數據提供機構識別碼, 例如: hk-dpo。
數據提供機構識別碼的完整列表如下:

數據提供機構識別碼	數據提供機構名稱
aahk	香港機場管理局
cc	消費者委員會
centaline	中原地產代理有限公司
cfs	食物安全中心
chsc	家庭與學校合作事宜委員會
ckf	全記渡有限公司
compcomm	競爭事務委員會
ctb	城巴有限公司
cyberport	香港數碼港管理有限公司
dc	區議會
eac	選舉管理委員會
ff	富裕小輪有限公司
hk-afcd	漁農自然護理署
hk-ams	醫療輔助隊
hk-archsd	建築署
hk-aud	審計署
hk-aw	政務司司長辦公室轄下行政署
hk-bd	屋宇署
hk-cad	民航處
hk-cas	民眾安全服務隊
hk-cedb	商務及經濟發展局
hk-cedd	土木工程拓展署
hk-censtatd	政府統計處
hk-ceo	行政長官辦公室
hk-cmab	政制及內地事務局
hk-cpu	中央政策組
hk-cepu	特首政策组
hk-cr	公司註冊處
hk-csb	公務員事務局
hk-csd	香港懲教署
hk-cso	政務司司長辦公室
hk-cstb	文化體育及旅遊局
hk-customs	香港海關
hk-devb	發展局
hk-dh	衞生署
hk-doj	律政司
hk-dpo	數字政策辦公室
hk-dsd	渠務署
hk-eabfu	經濟分析及方便營商處
hk-edb	教育局
hk-eeb	環境及生態局
hk-emsd	機電工程署
hk-epd	環境保護署
hk-fehd	食物環境衞生署
hk-fsd	香港消防處
hk-fso	財政司司長辦公室
hk-fstb	財經事務及庫務局
hk-gfs	政府飛行服務隊
hk-gld	政府物流服務署
hk-govtlab	政府化驗所
hk-gpa	政府產業署
hk-had	民政事務總署
hk-hhb	醫務衞生局
hk-hkma	香港金融管理局
hk-hko	香港天文台
hk-hkpf	香港警務處
hk-hkpo	香港郵政
hk-housing	香港房屋委員會
hk-hyab	民政及青年事務局
hk-hyd	路政署
hk-icac	廉政公署
hk-immd	入境事務處
hk-investhk	投資推廣署
hk-ipd	知識產權署
hk-ird	稅務局
hk-isd	政府新聞處
hk-itc	創新科技署
hk-itib	創新科技及工業局
hk-jsscs	公務及司法人員薪俸及服務條件諮詢委員會聯合秘書處
hk-lad	法律援助署
hk-landsd	地政總署
hk-lcsd	康樂及文化事務署
hk-ld	勞工處
hk-lr	土地註冊處
hk-lwb	勞工及福利局
hk-md	海事處
hk-ofca	通訊事務管理局辦公室
hk-ofnaa	電影、報刊及物品管理辦事處
hk-omb	申訴專員公署
hk-oro	破產管理署
hk-pland	規劃署
hk-psc	公務員敍用委員會
hk-reo	選舉事務處
hk-rthk	香港電台
hk-rvd	差餉物業估價署
hk-sb	保安局
hk-sciocs	截取通訊及監察事務專員秘書處
hk-swd	社會福利署
hk-td	運輸署
hk-tid	工業貿易署
hk-tlb	運輸及物流局
hk-try	庫務署
hk-ugc	大學教育資助委員會秘書處
hk-wfsfaa	在職家庭及學生資助事務處
hk-wsd	水務署
hkcert	香港網絡安全事故協調中心
hkeaa	香港考試及評核局
hkelectric	香港電燈有限公司
hkhs	香港房屋協會
hkirc	香港互聯網註冊管理有限公司
hkkf	港九小輪有限公司
hkpc	香港生產力促進局
hkstp	香港科技園公司
hktdc	香港貿易發展局
hktramways	香港電車有限公司
hospital	醫院管理局
ia	保險業監管局
legco	立法會
llb	酒牌局
mpfa	強制性公積金計劃管理局
mtr	香港鐵路有限公司
nlb	新大嶼山巴士 (1973) 有限公司
pckt	坪洲街渡有限公司
rehabsociety	香港復康會
starferry	天星小輪有限公司
sunferry	新渡輪服務有限公司
towngas	香港中華煤氣有限公司
tpd	城市規劃委員會
traway	翠華船務(香港)有限公司
ura	市區重建局
wkcda	西九文化區管理局

format 檔案格式，以檔案的副檔名，例如: xls。否

search 關鍵詞搜尋。只有與數據集／資源名稱匹配的結果會返回。否

order

排序。有效選項為: dataset-en，dataset-tc，dataset-sc，resource-en，resource-tc，resource-sc 和 url。預設排序為url。.

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

結果可以按如下排序：

數據集和資源名稱 - 如order是按dataset-en，dataset-tc 或 dataset-sc。
資源名稱 - 如order是按resource-en, resource-tc or resource-sc。
網址 - 如order是按url。

否

skip 首x個記錄會被省略。否

參數

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	法律及保安
legislature	選舉及立法機關
miscellaneous	其他
population	人口
recreation-and-culture	康樂、體育及文化
social-welfare	社區及社會福利
transport	運輸

必要

否

參數

provider

描述

數據提供機構識別碼, 例如: hk-dpo。
數據提供機構識別碼的完整列表如下:

數據提供機構識別碼	數據提供機構名稱
aahk	香港機場管理局
cc	消費者委員會
centaline	中原地產代理有限公司
cfs	食物安全中心
chsc	家庭與學校合作事宜委員會
ckf	全記渡有限公司
compcomm	競爭事務委員會
ctb	城巴有限公司
cyberport	香港數碼港管理有限公司
dc	區議會
eac	選舉管理委員會
ff	富裕小輪有限公司
hk-afcd	漁農自然護理署
hk-ams	醫療輔助隊
hk-archsd	建築署
hk-aud	審計署
hk-aw	政務司司長辦公室轄下行政署
hk-bd	屋宇署
hk-cad	民航處
hk-cas	民眾安全服務隊
hk-cedb	商務及經濟發展局
hk-cedd	土木工程拓展署
hk-censtatd	政府統計處
hk-ceo	行政長官辦公室
hk-cmab	政制及內地事務局
hk-cpu	中央政策組
hk-cepu	特首政策组
hk-cr	公司註冊處
hk-csb	公務員事務局
hk-csd	香港懲教署
hk-cso	政務司司長辦公室
hk-cstb	文化體育及旅遊局
hk-customs	香港海關
hk-devb	發展局
hk-dh	衞生署
hk-doj	律政司
hk-dpo	數字政策辦公室
hk-dsd	渠務署
hk-eabfu	經濟分析及方便營商處
hk-edb	教育局
hk-eeb	環境及生態局
hk-emsd	機電工程署
hk-epd	環境保護署
hk-fehd	食物環境衞生署
hk-fsd	香港消防處
hk-fso	財政司司長辦公室
hk-fstb	財經事務及庫務局
hk-gfs	政府飛行服務隊
hk-gld	政府物流服務署
hk-govtlab	政府化驗所
hk-gpa	政府產業署
hk-had	民政事務總署
hk-hhb	醫務衞生局
hk-hkma	香港金融管理局
hk-hko	香港天文台
hk-hkpf	香港警務處
hk-hkpo	香港郵政
hk-housing	香港房屋委員會
hk-hyab	民政及青年事務局
hk-hyd	路政署
hk-icac	廉政公署
hk-immd	入境事務處
hk-investhk	投資推廣署
hk-ipd	知識產權署
hk-ird	稅務局
hk-isd	政府新聞處
hk-itc	創新科技署
hk-itib	創新科技及工業局
hk-jsscs	公務及司法人員薪俸及服務條件諮詢委員會聯合秘書處
hk-lad	法律援助署
hk-landsd	地政總署
hk-lcsd	康樂及文化事務署
hk-ld	勞工處
hk-lr	土地註冊處
hk-lwb	勞工及福利局
hk-md	海事處
hk-ofca	通訊事務管理局辦公室
hk-ofnaa	電影、報刊及物品管理辦事處
hk-omb	申訴專員公署
hk-oro	破產管理署
hk-pland	規劃署
hk-psc	公務員敍用委員會
hk-reo	選舉事務處
hk-rthk	香港電台
hk-rvd	差餉物業估價署
hk-sb	保安局
hk-sciocs	截取通訊及監察事務專員秘書處
hk-swd	社會福利署
hk-td	運輸署
hk-tid	工業貿易署
hk-tlb	運輸及物流局
hk-try	庫務署
hk-ugc	大學教育資助委員會秘書處
hk-wfsfaa	在職家庭及學生資助事務處
hk-wsd	水務署
hkcert	香港網絡安全事故協調中心
hkeaa	香港考試及評核局
hkelectric	香港電燈有限公司
hkhs	香港房屋協會
hkirc	香港互聯網註冊管理有限公司
hkkf	港九小輪有限公司
hkpc	香港生產力促進局
hkstp	香港科技園公司
hktdc	香港貿易發展局
hktramways	香港電車有限公司
hospital	醫院管理局
ia	保險業監管局
legco	立法會
llb	酒牌局
mpfa	強制性公積金計劃管理局
mtr	香港鐵路有限公司
nlb	新大嶼山巴士 (1973) 有限公司
pckt	坪洲街渡有限公司
rehabsociety	香港復康會
starferry	天星小輪有限公司
sunferry	新渡輪服務有限公司
towngas	香港中華煤氣有限公司
tpd	城市規劃委員會
traway	翠華船務(香港)有限公司
ura	市區重建局
wkcda	西九文化區管理局

必要

否

參數

format

描述

檔案格式，以檔案的副檔名，例如: xls。

必要

否

參數

描述

關鍵詞搜尋。只有與數據集／資源名稱匹配的結果會返回。

必要

否

參數

order

描述

數據集和資源名稱 - 如order是按dataset-en，dataset-tc 或 dataset-sc。
資源名稱 - 如order是按resource-en, resource-tc or resource-sc。
網址 - 如order是按url。

必要

否

參數

skip

描述

首x個記錄會被省略。

必要

否

2. 歷史存檔文件版本API

API端點

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

HTTP請求方法： GET

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

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

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

參數

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	以`YYYYMMDD`格式的開始日期（包括首日）, 例如: 20160101。	是
time	檔案網址，網址可從歷史檔案文件列表應用程式介面結果中找到。	是

參數

url

參數

以YYYYMMDD格式的開始日期（包括首日）, 例如: 20160101。

必要

是

參數

time

參數

檔案網址，網址可從歷史檔案文件列表應用程式介面結果中找到。

必要

是

補充資訊:

所有時間均以GMT + 8時區為準。
最新的歷史數據來自昨天。

4. 歷史存檔模式下載API

API端點

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

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

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

參數

url

參數

數據集的網址

必要

是

參數

date

參數

以YYYYMMDD格式的日期, 例如: 20160101。

必要

是

5. 歷史存檔數據字典API

API端點

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

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

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

參數

url

參數

數據集的網址

必要

是

參數

date

參數

以YYYYMMDD格式的日期, 例如: 20160101。

必要

是

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

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

API端點

https://api.data.gov.hk/v2/filter

注意：本應用程式介面最新版本為2，我們仍然支援版本1。

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

輸入

查詢字串輸入參數

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

名稱

值說明

網址編碼(URL-Encoded) JSON 物件字串(有關詳細信息，請參閱以下描述)

必要

是

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

成員/名字	JSON 數據類型	值說明	必要
resource	string	URL資源. URL可以在本頁的頂部找到	是
section	number	章節編號（僅在"數據部分"可用時才需要）由1開始的正整數 (預設: 1)	否
filter	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	否

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

成員/名字

resource

JSON 數據類型

string

值說明

URL資源. URL可以在本頁的頂部找到

必要

是

成員/名字

section

JSON 數據類型

number

值說明

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

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

必要

否

成員/名字

filter

JSON 數據類型

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

JSON 數據類型

array

值說明

排序條件的數據陣列：
[ [S1], [S2], ..., [Sn] ]

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

Sn = [ Cn, "ORDER" ]

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

asc - 升序
desc - 降序

必要

否

例子

輸入

resource = 資源URL

section = 1,

篩選條件及排序條件為：

欄位編號 1 中，其值等於 “abc” 和，

欄位編號 1 中，其值不等於 “xyz”和，

欄位編號 3 ，排序為升序和，

欄位編號 4 ，排序為降序

format（輸出格式）= JSON,

JSON 物件

{
  “resource”: “https://api.data.gov.hk/v2/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

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

輸入

查詢字串輸入參數

輸入

lat:	查詢地點之緯度(WGS84)
long:	查詢地點之經度(WGS84)
max:	限制回覆結果的數目(預設:全部，上限:100)

輸出 [JSON 物件]

results: 以與查詢地點距離順序排列的結果

注意:
本應用程式介面(介面)由「開放數據平台」團隊開發，旨在為軟件及應用程式開發商提供使用原始數據集的不同角度和方法。經由本介面產生的數據子集，或未載有原始數據集內由數據提供者提供的全部資料。使用本介面時，務須參考原始數據集，以掌握全面資料。

應用程式介面規範

應用程式 介面規格

下載歷史數據應用程式介面

數據篩選應用程式介面

尋找附近設施應用程式介面

應用程式介面規格