API SPECIFICATION

A place that can help you check learning tutorials and materials about DATA.GOV.HK

1. Historical Archive File List API

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 Required
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.
The full list of the Category ID is listed below:
Category ID Category Name
city-managementCity Management
climate-and-weatherClimate and Weather
commerce-and-industryCommerce and Industry
developmentDevelopment
educationEducation
employment-and-labourEmployment and Labour
environmentEnvironment
financeFinance
foodFood
healthHealth
housingHousing
information-technology-and-broadcastingIT and Broadcasting
law-and-securityLaw and Security
populationPopulation
recreation-and-cultureRecreation and Culture
social-welfareSocial Welfare
transportTransport
miscellaneousMiscellaneous
No
provider Provider ID, e.g.: hk-ogcio. 
The full list of the Provider ID is listed below::
Provider ID Provider Name
hk-afcdAgriculture, Fisheries and Conservation Department
hk-archsdArchitectural Services Department
hk-bdBuildings Department
hk-cadCivil Aviation Department
hk-ceddCivil Engineering and Development Department
hk-censtatdCensus and Statistics Department
hk-crCompanies Registry
hk-csdCorrectional Services Department
hk-customsCustoms and Excise Department
hk-dhDepartment of Health
hk-devbDevelopment Bureau
hk-edbEducation Bureau
hk-emsdElectrical and Mechanical Services Department
hk-epdEnvironmental Protection Department
hk-effoEfficiency Office
hk-fehdFood and Environmental Hygiene Department
hk-fsoFinancial Secretary's Office
hk-fstbFinancial Services and the Treasury Bureau
hk-gldGovernment Logistics Department
hk-govtlabGovernment Laboratory
hk-gpaGovernment Property Agency
hk-hkoHong Kong Observatory
hk-hkpfHong Kong Police Force
hk-housingHong Kong Housing Authority
hk-ipdIntellectual Property Department
hk-irdInland Revenue Department
hk-isdInformation Services Department
hk-itcInnovation and Technology Commission
hk-landsdLands Department
hk-lcsdLeisure and Cultural Services Department
hk-lrLand Registry
hk-mdMarine Department
hk-ofcaOffice of the Communications Authority
hk-ofnaaOffice for Film, Newspaper and Article Administration
hk-ogcioOffice of the Government Chief Information Officer
hk-oroOfficial Receiver's Office
hk-plandPlanning Department
hk-reoRegistration and Electoral Office
hk-rthkRadio Television Hong Kong
hk-rvdRating and Valuation Department
hk-swdSocial Welfare Department
hk-tdTransport Department
hk-tidTrade and Industry Department
hk-tryTreasury
hk-ugcUniversity Grants Committee Secretariat
hk-wfsfaaWorking Family and Student Financial Assistance Agency
centalineCentaline Property Agency Limited
clpCLP Power Hong Kong Limited
ctbCitybus Limited
hkelectricThe Hongkong Electric Company, Limited
mtrMTR Corporation Limited
nlbNew Lantao Bus Company (1973) Limited
nwfbNew World First Bus Services Limited
rehabsocietyThe Hong Kong Society for Rehabilitation
hktramwaysHong Kong Tramways, Limited
hkeaaHong Kong Examinations and Assessment Authority
iaInsurance Authority
hospitalHospital Authority
starferryThe "Star" Ferry Company, Limited
hkhsHong Kong Housing Society
hkcertHong Kong Computer Emergency Response Team Coordination Centre
hk-ceoChief Executive's Office
hk-ociOffice of the Commissioner of Insurance (Disbanded)
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

2. Historical Archive File Version API

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 Required
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

3. Historical Archive File Download API

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 URL of a file, the URL can be found in the Historical Archive File List API result. Yes
time Exact date and time of an archived file in YYYYMMDD-hhmm format, e.g.: 20160101-0000. Yes
Supplementary information:
  • All time is based on GMT+8 time zone.
  • The latest available Historical Data are from yesterday.

4. Historical Archive Schema Download API

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

HTTP Request Method: GET

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 Required
url URL of a dataset. Yes
date Date in YYYYMMDD format, e.g.: 20160101. Yes

5. Historical Archive Data Dictionary Download API

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

HTTP Request Method: GET

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 Required
url URL of a dataset. Yes
date Date in YYYYMMDD format, e.g.: 20160101. Yes

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

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

API endpoint: https://api.data.gov.hk/v1/filter

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

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
filters 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" ]

Where,
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

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/v1/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 format]
results: List of results, in ascending order of distance to the specified location
Note:
This application Programming Interface (API) s developed by the DATA.GOV.HK team with ouroise to provide software and application developers with different perspectives and means on using the original datsets(s). The resulted subset(s) of data delivered via th API may not carry the completer informatin that is provided in the original dataset(s) from the providing agencies. One should always make reference to the original datasets(s) for a comprehensive application