API Specification

API Specification

We have come up with different API builders to help you extract the data based on your Query, or Historical Data. This section has all the help you need to know more about coming up with APIs.

API Endpoint:

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

HTTP Request Method: GET
Retrieves a list of files that are available within the given period specified in start and end and match the values specified in the category, provider and format parameters.

At most max number of results will be returned, with the first number of skip items omitted. Pagination can be achieved by utilizing these two parameters.

Status code 200 will be returned along with a list of file and the total result count in JSON format if it is a successful call.
Status code 400 will be returned along with a list of error in JSON format if the request contains syntax error(s) such as missing required parameter.

Parameter Description of Value Mandatory?
start Start data of a period (inclusive) in YYYYMMDD format, e.g.: 20160101 Yes
end End data of a period (inclusive) in YYYYMMDD format, e.g.: 20161231 Yes
category Category ID, e.g.: information-technology-and-broadcasting.
Category ID Category Name
city-management City Management and Utilities
climate-and-weather Climate and Weather
commerce-and-industry Commerce and Industry
development Development, Geography and Land Information
education Education
employment-and-labour Employment and Labour
environment Environment
finance Finance
food Food
health Health
housing Housing
information-technology-and-broadcasting Technology and Broadcasting
law-and-security Law and Security
legislature Election and Legislature
miscellaneous Miscellaneous
population Population
recreation-and-culture Recreation, Sports and Culture
social-welfare Community and Social Welfare
transport Transportation
No
provider Provider ID, e.g.: hk-dpo. 
The full list of the Provider ID is listed below:
Provider ID Provider Name
aahk Airport Authority Hong Kong
cc Consumer Council
centaline Centaline Property Agency Limited
cfs Centre for Food Safety
chsc Committee on Home-School Co-operation
ckf Chuen Kee Ferry Limited
compcomm Competition Commission
ctb Citybus Limited
cyberport Hong Kong Cyberport Management Company Limited
dc District Councils
eac Electoral Affairs Commission
ff Fortune Ferry Company Limited
hk-afcd Agriculture, Fisheries and Conservation Department
hk-ams Auxiliary Medical Service
hk-archsd Architectural Services Department
hk-aud Audit Commission
hk-aw Administration Wing, Chief Secretary for Administration's Office
hk-bd Buildings Department
hk-cad Civil Aviation Department
hk-cas Civil Aid Service
hk-cedb Commerce and Economic Development Bureau
hk-cedd Civil Engineering and Development Department
hk-censtatd Census and Statistics Department
hk-ceo Chief Executive's Office
hk-cmab Constitutional and Mainland Affairs Bureau
hk-cpu Central Policy Unit
hk-cepu Chief Executive's Policy Unit
hk-cr Companies Registry
hk-csb Civil Service Bureau
hk-csd Correctional Services Department
hk-cso Chief Secretary for Administration's Office
hk-cstb Culture, Sports and Tourism Bureau
hk-customs Customs and Excise Department
hk-devb Development Bureau
hk-dh Department of Health
hk-doj Department of Justice
hk-dpo Digital Policy Office
hk-dsd Drainage Services Department
hk-eabfu Economic Analysis and Business Facilitation Unit
hk-edb Education Bureau
hk-eeb Environment and Ecology Bureau
hk-emsd Electrical and Mechanical Services Department
hk-epd Environmental Protection Department
hk-fehd Food and Environmental Hygiene Department
hk-fsd Fire Services Department
hk-fso Financial Secretary's Office
hk-fstb Financial Services and the Treasury Bureau
hk-gfs Government Flying Service
hk-gld Government Logistics Department
hk-govtlab Government Laboratory
hk-gpa Government Property Agency
hk-had Home Affairs Department
hk-hhb Health Bureau
hk-hkma Hong Kong Monetary Authority
hk-hko Hong Kong Observatory
hk-hkpf Hong Kong Police Force
hk-hkpo Hongkong Post
hk-housing Hong Kong Housing Authority
hk-hyab Home and Youth Affairs Bureau
hk-hyd Highways Department
hk-icac Independent Commission Against Corruption
hk-immd Immigration Department
hk-investhk Invest Hong Kong
hk-ipd Intellectual Property Department
hk-ird Inland Revenue Department
hk-isd Information Services Department
hk-itc Innovation and Technology Commission
hk-itib Innovation, Technology and Industry Bureau
hk-jsscs Joint Secretariat for the Advisory Bodies on Civil Service and Judicial Salaries and Conditions of Service
hk-lad Legal Aid Department
hk-landsd Lands Department
hk-lcsd Leisure and Cultural Services Department
hk-ld Labour Department
hk-lr Land Registry
hk-lwb Labour and Welfare Bureau
hk-md Marine Department
hk-ofca Office of the Communications Authority
hk-ofnaa Office for Film, Newspaper and Article Administration
hk-omb Office of the Ombudsman
hk-oro Official Receiver's Office
hk-pland Planning Department
hk-psc Public Service Commission
hk-reo Registration and Electoral Office
hk-rthk Radio Television Hong Kong
hk-rvd Rating and Valuation Department
hk-sb Security Bureau
hk-sciocs Secretariat, Commissioner on Interception of Communications and Surveillance
hk-swd Social Welfare Department
hk-td Transport Department
hk-tid Trade and Industry Department
hk-tlb Transport and Logistics Bureau
hk-try Treasury
hk-ugc University Grants Committee Secretariat
hk-wfsfaa Working Family and Student Financial Assistance Agency
hk-wsd Water Supplies Department
hkcert Hong Kong Computer Emergency Response Team Coordination Centre
hkeaa Hong Kong Examinations and Assessment Authority
hkelectric The Hongkong Electric Company, Limited
hkhs Hong Kong Housing Society
hkirc Hong Kong Internet Registration Corporation Limited
hkkf Hong Kong & Kowloon Ferry Limited
hkpc Hong Kong Productivity Council
hkstp Hong Kong Science and Technology Parks Corporation
hktdc Hong Kong Trade Development Council
hktramways Hong Kong Tramways, Limited
hospital Hospital Authority
ia Insurance Authority
legco Legislative Council
llb Liquor Licensing Board
mpfa Mandatory Provident Fund Schemes Authority
mtr MTR Corporation Limited
nlb New Lantao Bus Company (1973) Limited
pckt Peng Chau Kai To Limited
rehabsociety The Hong Kong Society for Rehabilitation
starferry The "Star" Ferry Company, Limited
sunferry Sun Ferry Services Company Limited
towngas The Hong Kong and China Gas Company Limited
tpd Town Planning Board
traway Tsui Wah Ferry Service (H.K.) Limited
ura Urban Renewal Authority
wkcda West Kowloon Cultural District Authority
No
format File format, in its file format extension, e.g.: xls. No
search Keyword search. Only the matching results with the dataset/resource names will be returned. No
order Sort order. Valid options are: dataset-en, dataset-tc, dataset-sc, resource-en, resource-tc, resource-sc and url. Default is by url..

The -en/-tc/-sc suffix denotes the respective language field for ordering.

The results can be sorted by:
  1. dataset name and resource name - if order is by dataset-en, dataset-tc or dataset-sc.
  2. resource name - if order is by resource-en, resource-tc or resource-sc.
  3. URL, if order is by url.
No
skip The first x number of records to omit. No

Parameter

start

Description of Value

Start data of a period (inclusive) in YYYYMMDD format, e.g.: 20160101

Mandatory?

Yes

Parameter

end

Description of Value

End data of a period (inclusive) in YYYYMMDD format, e.g.: 20161231

Mandatory?

Yes

Parameter

category

Description of Value

Category ID, e.g.: information-technology-and-broadcasting.

Category ID Category Name
city-management City Management and Utilities
climate-and-weather Climate and Weather
commerce-and-industry Commerce and Industry
development Development, Geography and Land Information
education Education
employment-and-labour Employment and Labour
environment Environment
finance Finance
food Food
health Health
housing Housing
information-technology-and-broadcasting Technology and Broadcasting
law-and-security Law and Security
legislature Election and Legislature
miscellaneous Miscellaneous
population Population
recreation-and-culture Recreation, Sports and Culture
social-welfare Community and Social Welfare
transport Transportation

Mandatory?

No

Parameter

provider

Description of Value

Provider ID, e.g.: hk-dpo. 
The full list of the Provider ID is listed below:

Provider ID Provider Name
aahk Airport Authority Hong Kong
cc Consumer Council
centaline Centaline Property Agency Limited
cfs Centre for Food Safety
chsc Committee on Home-School Co-operation
ckf Chuen Kee Ferry Limited
compcomm Competition Commission
ctb Citybus Limited
cyberport Hong Kong Cyberport Management Company Limited
dc District Councils
eac Electoral Affairs Commission
ff Fortune Ferry Company Limited
hk-afcd Agriculture, Fisheries and Conservation Department
hk-ams Auxiliary Medical Service
hk-archsd Architectural Services Department
hk-aud Audit Commission
hk-aw Administration Wing, Chief Secretary for Administration's Office
hk-bd Buildings Department
hk-cad Civil Aviation Department
hk-cas Civil Aid Service
hk-cedb Commerce and Economic Development Bureau
hk-cedd Civil Engineering and Development Department
hk-censtatd Census and Statistics Department
hk-ceo Chief Executive's Office
hk-cmab Constitutional and Mainland Affairs Bureau
hk-cpu Central Policy Unit
hk-cepu Chief Executive's Policy Unit
hk-cr Companies Registry
hk-csb Civil Service Bureau
hk-csd Correctional Services Department
hk-cso Chief Secretary for Administration's Office
hk-cstb Culture, Sports and Tourism Bureau
hk-customs Customs and Excise Department
hk-devb Development Bureau
hk-dh Department of Health
hk-doj Department of Justice
hk-dpo Digital Policy Office
hk-dsd Drainage Services Department
hk-eabfu Economic Analysis and Business Facilitation Unit
hk-edb Education Bureau
hk-eeb Environment and Ecology Bureau
hk-emsd Electrical and Mechanical Services Department
hk-epd Environmental Protection Department
hk-fehd Food and Environmental Hygiene Department
hk-fsd Fire Services Department
hk-fso Financial Secretary's Office
hk-fstb Financial Services and the Treasury Bureau
hk-gfs Government Flying Service
hk-gld Government Logistics Department
hk-govtlab Government Laboratory
hk-gpa Government Property Agency
hk-had Home Affairs Department
hk-hhb Health Bureau
hk-hkma Hong Kong Monetary Authority
hk-hko Hong Kong Observatory
hk-hkpf Hong Kong Police Force
hk-hkpo Hongkong Post
hk-housing Hong Kong Housing Authority
hk-hyab Home and Youth Affairs Bureau
hk-hyd Highways Department
hk-icac Independent Commission Against Corruption
hk-immd Immigration Department
hk-investhk Invest Hong Kong
hk-ipd Intellectual Property Department
hk-ird Inland Revenue Department
hk-isd Information Services Department
hk-itc Innovation and Technology Commission
hk-itib Innovation, Technology and Industry Bureau
hk-jsscs Joint Secretariat for the Advisory Bodies on Civil Service and Judicial Salaries and Conditions of Service
hk-lad Legal Aid Department
hk-landsd Lands Department
hk-lcsd Leisure and Cultural Services Department
hk-ld Labour Department
hk-lr Land Registry
hk-lwb Labour and Welfare Bureau
hk-md Marine Department
hk-ofca Office of the Communications Authority
hk-ofnaa Office for Film, Newspaper and Article Administration
hk-omb Office of the Ombudsman
hk-oro Official Receiver's Office
hk-pland Planning Department
hk-psc Public Service Commission
hk-reo Registration and Electoral Office
hk-rthk Radio Television Hong Kong
hk-rvd Rating and Valuation Department
hk-sb Security Bureau
hk-sciocs Secretariat, Commissioner on Interception of Communications and Surveillance
hk-swd Social Welfare Department
hk-td Transport Department
hk-tid Trade and Industry Department
hk-tlb Transport and Logistics Bureau
hk-try Treasury
hk-ugc University Grants Committee Secretariat
hk-wfsfaa Working Family and Student Financial Assistance Agency
hk-wsd Water Supplies Department
hkcert Hong Kong Computer Emergency Response Team Coordination Centre
hkeaa Hong Kong Examinations and Assessment Authority
hkelectric The Hongkong Electric Company, Limited
hkhs Hong Kong Housing Society
hkirc Hong Kong Internet Registration Corporation Limited
hkkf Hong Kong & Kowloon Ferry Limited
hkpc Hong Kong Productivity Council
hkstp Hong Kong Science and Technology Parks Corporation
hktdc Hong Kong Trade Development Council
hktramways Hong Kong Tramways, Limited
hospital Hospital Authority
ia Insurance Authority
legco Legislative Council
llb Liquor Licensing Board
mpfa Mandatory Provident Fund Schemes Authority
mtr MTR Corporation Limited
nlb New Lantao Bus Company (1973) Limited
pckt Peng Chau Kai To Limited
rehabsociety The Hong Kong Society for Rehabilitation
starferry The "Star" Ferry Company, Limited
sunferry Sun Ferry Services Company Limited
towngas The Hong Kong and China Gas Company Limited
tpd Town Planning Board
traway Tsui Wah Ferry Service (H.K.) Limited
ura Urban Renewal Authority
wkcda West Kowloon Cultural District Authority

Mandatory?

No

Parameter

format

Description of Value

File format, in its file format extension, e.g.: xls.

Mandatory?

No

Parameter

search

Description of Value

Keyword search. Only the matching results with the dataset/resource names will be returned.

Mandatory?

No

Parameter

order

Description of Value

Sort order. Valid options are: dataset-en, dataset-tc, dataset-sc, resource-en, resource-tc, resource-sc and url. Default is by url..

The -en/-tc/-sc suffix denotes the respective language field for ordering.

The results can be sorted by:

  1. dataset name and resource name - if order is by dataset-en, dataset-tc or dataset-sc.
  2. resource name - if order is by resource-en, resource-tc or resource-sc.
  3. URL, if order is by url.

Mandatory?

No

Parameter

skip

Description of Value

The first x number of records to omit.

Mandatory?

No

API Endpoint:

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

HTTP Request Method: GET

Retrieves the list of historical version of a file (given in url) within a date period (given in start and end).
Only the first 10,000 results will be returned.

Status code 200 will be returned along with a list of historical version timestamps, total count and the total size in bytes in JSON format if it is a successful call.
Status code 400 will be returned along with a list of error in JSON format if the request contains syntax error(s) such as missing required parameter.

Parameter Description of Value Mandatory?
url URL of a file, the URL can be found from the Historical Archive File List API result above. Yes
start Start data of a period (inclusive) in YYYYMMDD format, e.g.: 20160101 Yes
end End data of a period (inclusive) in YYYYMMDD format, e.g.: 20161231 Yes

Parameter

url

Description

URL of a file, the URL can be found from the Historical Archive File List API result above.

Required

Yes

Parameter

start

Description

Start data of a period (inclusive) in YYYYMMDD format, e.g.: 20160101

Required

Yes

Parameter

end

Description

End data of a period (inclusive) in YYYYMMDD format, e.g.: 20161231

Required

Yes

API Endpoint:

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

HTTP Request Method: GET

Retrieves a historical version of a specific file (given in url) based on the given time.

Status code 302 will be returned if it is a successful call, the requester should then follow the redirection and receive a Status code 200 along with the requesting file.
Status code 400 will be returned along with a list of error in JSON format if the request contains syntax error(s) such as missing required parameter.
Status code 404 will be returned along with a list of error in JSON format if the requesting historical version of the file is not available.

Parameter Description Required
url Start data of a period (inclusive) in YYYYMMDD format, e.g.: 20160101 Yes
time URL of a file, the URL can be found in the Historical Archive File List API result. Yes

Parameter

url

Description

Start data of a period (inclusive) in YYYYMMDD format, e.g.: 20160101

Required

Yes

Parameter

time

Description

URL of a file, the URL can be found in the Historical Archive File List API result.

Required

Yes

Supplementary information:

  • All time is based on GMT+8 time zone.
  • The latest available Historical Data are from yesterday.

API Endpoint:

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

Retrieves a historical version of a specific schema (given in its dataset url) based on the given date.

Status code 302 will be returned if it is a successful call, the requester should then follow the redirection and receive a Status code 200 along with the requesting file.
Status code 400 will be returned along with a list of error in JSON format if the request contains syntax error(s) such as missing required parameter.
Status code 404 will be returned along with a list of error in JSON format if the requesting historical version of the file is not available.

Parameter Description of Value Mandatory?
url URL of a dataset. Yes
date Date in YYYYMMDD format, e.g.: 20160101. Yes

Parameter

url

Description

URL of a dataset.

Required

Yes

Parameter

date

Description

Date in YYYYMMDD format, e.g.: 20160101.

Required

Yes

API Endpoint:

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

Retrieves a historical version of a specific data dictionary (given in its dataset url) based on the given date.

Status code 302 will be returned if it is a successful call, the requester should then follow the redirection and receive a Status code 200 along with the requesting file.
Status code 400 will be returned along with a list of error in JSON format if the request contains syntax error(s) such as missing required parameter.
Status code 404 will be returned along with a list of error in JSON format if the requesting historical version of the file is not available.

Parameter Description of Value Mandatory?
url URL of a dataset. Yes
date Date in YYYYMMDD format, e.g.: 20160101. Yes

Parameter

url

Description

URL of a dataset.

Required

Yes

Parameter

date

Description

Date in YYYYMMDD format, e.g.: 20160101.

Required

Yes

EXAMPLE:
F101 USUAL RESIDENTS BY AGE, YEAR AND SEX (ENGLISH)

F101 Usual Residents by Age, Year and Sex
URL: https://www.bycensus2016.gov.hk/Page/Maintables/source/eng/F101/Result.xlsx

API Endpoint:

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

Note: Latest version for this API is 2, with version 1 still supported.

This API accepts query string input

INPUT

Query string input parameter(s)

Name Description of Value Mandatory?
q URL-Encoded JSON Object String (See below description for the details) Yes

Name

q

Description of Value

URL-Encoded JSON Object String (See below description for the details)

Mandatory?

Yes

JSON Object String specification for query string parameter “q”

Member / Name JSON Type Description of Value Mandatory?
resource string URL of resource. The URL can be found at the top of this page. Yes
section number

Section number (only required if “data section” is available)

  • Positive integer starting from 1 (default: 1)
No
filter array

An array of filtering conditions:

[ [F1], [F2], …, [Fn] ]

Where F is the filtering condition. Each filtering condition is an array with 3 elements denoted below:

Fn = [ Cn, “OP”, [ “O1”, “O2”, …, “On” ] ]

Where,
Cn is column number (number)
OP is filter operator (string), the following is the list of supported filter operators:

eq - is equal to
ne - is not equal to
in - is in (for text only)
ni - is not in (for text only)
lt - is less than (for number only)
le - is less than or equal to (for number only)
gt - is greater than (for number only)
ge - is greater than or equal to (for number only)
bt - is between (for number only)
ct - contains (for text only)
nct - does not contain (for text only)
bw - begins with (for text only)
nbw - does not begin with (for text only)
ew - ends with (for text only)
new - does not end with (for text only)

[ “O1”, “O2”, …, “On” ] is an array of filter operand O (string).

For filter operator, OP = bw (is between), 2 operands are required.

For filter operator = in (is in) or ni (is not in), 2 or more operands are required.

For the rest of filter operators, only 1 operand is required.

No
sorts array

An array of sorting order(s):
[ [S1], [S2], …, [Sn] ]

Where S is the sorting condition. Each sorting condition is an array with 2 elements denoted below

Sn = [ Cn, “ORDER” ]

Cn is column number (number)
ORDER is sorting order (string),
this options can have thefollowing values:

asc - in ascending order
desc - in descending order

No
format string

Output Format:

CSV (default)
json
xml

No

JSON Object String specification for query string parameter “q”

Member / Name

resource

JSON Type

string

Description of Value

URL of resource. The URL can be found at the top of this page.

Mandatory?

Yes

Member / Name

section

JSON Type

number

Description of Value

Section number (only required if “data section” is available)

  • Positive integer starting from 1 (default: 1)

Mandatory?

No

Member / Name

filter

JSON Type

array

An array of filtering conditions:

[ [F1], [F2], …, [Fn] ]

Where F is the filtering condition. Each filtering condition is an array with 3 elements denoted below:

Fn = [ Cn, “OP”, [ “O1”, “O2”, …, “On” ] ]

Where,
Cn is column number (number)
OP is filter operator (string), the following is the list of supported filter operators:

eq - is equal to
ne - is not equal to
in - is in (for text only)
ni - is not in (for text only)
lt - is less than (for number only)
le - is less than or equal to (for number only)
gt - is greater than (for number only)
ge - is greater than or equal to (for number only)
bt - is between (for number only)
ct - contains (for text only)
nct - does not contain (for text only)
bw - begins with (for text only)
nbw - does not begin with (for text only)
ew - ends with (for text only)
new - does not end with (for text only)

[ “O1”, “O2”, …, “On” ] is an array of filter operand O (string).

For filter operator, OP = bw (is between), 2 operands are required.

For filter operator = in (is in) or ni (is not in), 2 or more operands are required.

For the rest of filter operators, only 1 operand is required.

Mandatory?

No

Member / Name

sorts

JSON Type

array

Description of Value

An array of sorting order(s):
[ [S1], [S2], …, [Sn] ]

Where S is the sorting condition. Each sorting condition is an array with 2 elements denoted below

Sn = [ Cn, “ORDER” ]

Cn is column number (number)
ORDER is sorting order (string),
this options can have thefollowing values:

asc - in ascending order
desc - in descending order

Mandatory?

No

Example

INPUT

resource = URL of resource

section = 1,

Filter and sorting:

Column 1 is equal to “abc” AND

Column 1 is not equal to “xyz” AND

Sort Column 3 in ascending order AND

Sort Column 4 in descending order AND

Format (Output) = JSON

JSON Object

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

Output [JSON Object]

CSV, JSON or XML file as specified by the “format” parameter in the above JSON Object string.

EXAMPLE:
NEAREST SCHOOL TO A LOCATION

Find the nearest school given a location (latitude and longitude)
Dataset used: School Location and Information

API Endpoint:

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

This API accepts query string input

INPUT

Query string input parameter(s)

INPUT

lat: Latitude of enquiry location (WGS84)
long: Longitude of enquiry location (WGS84)
max: Maximum number of results returned (default: all, limit:100)

Output [JSON Object]

results: List of results, in ascending order of distance to the specified location

Note:
This Application Programming Interface (API) is developed by the DATA.GOV.HK team with the purpose to provide software and application developers with different perspectives and means on using the original dataset(s). The resulted subset(s) of data delivered via the API may not carry the complete information that is provided in the original dataset(s) from the providing agencies. One should always make reference to the original dataset(s) for a comprehensive application.

Access to save data on the browser is disabled, some functions may not be available.

Please enable the access to unlock the full functionality of the website.