应用程式介面规范

应用程式介面规格

一个可以帮助您检查有关「开放数据平台」的学习教程和资料的地方

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: 以与查询地点距离顺序排列的结果

注意:
本应用程式介面(介面)由「开放数据平台」团队开发，旨在为软件及应用程式开发商提供使用原始数据集的不同角度和方法。经由本介面产生的数据子集，或未载有原始数据集内由数据提供者提供的全部资料。使用本介面时，务须参考原始数据集，以掌握全面资料。

应用程式介面规范

应用程式 介面规格

下载历史数据应用程式介面

数据筛选应用程式介面

寻找附近设施应用程式介面

应用程式介面规格