1. Home
  2. Help
  3. API Specification

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.
:
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
legislatureLegislature
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-amsAuxiliary Medical Service
hk-archsdArchitectural Services Department
hk-audAudit Commission
hk-awAdministration Wing, Chief Secretary for Administration's Office
hk-bdBuildings Department
hk-cadCivil Aviation Department
hk-casCivil Aid Service
hk-cedbCommerce and Economic Development Bureau
hk-ceddCivil Engineering and Development Department
hk-censtatdCensus and Statistics Department
hk-ceoChief Executive's Office
hk-cmabConstitutional and Mainland Affairs Bureau
hk-crCompanies Registry
hk-csbCivil Service Bureau
hk-csdCorrectional Services Department
hk-csoChief Secretary for Administration's Office
hk-cstbCulture, Sports and Tourism Bureau
hk-customsCustoms and Excise Department
hk-devbDevelopment Bureau
hk-dhDepartment of Health
hk-dojDepartment of Justice
hk-dsdDrainage Services Department
hk-edbEducation Bureau
hk-eebEnvironment and Ecology Bureau
hk-effoEfficiency Office
hk-emsdElectrical and Mechanical Services Department
hk-epdEnvironmental Protection Department
hk-fehdFood and Environmental Hygiene Department
hk-fsdFire Services Department
hk-fsoFinancial Secretary's Office
hk-fstbFinancial Services and the Treasury Bureau
hk-gfsGovernment Flying Service
hk-gldGovernment Logistics Department
hk-govtlabGovernment Laboratory
hk-gpaGovernment Property Agency
hk-hadHome Affairs Department
hk-hbHousing Bureau
hk-hhbHealth Bureau
hk-hkmaHong Kong Monetary Authority
hk-hkoHong Kong Observatory
hk-hkpfHong Kong Police Force
hk-hkpoHongkong Post
hk-housingHong Kong Housing Authority
hk-hyabHome and Youth Affairs Bureau
hk-hydHighways Department
hk-icacIndependent Commission Against Corruption
hk-immdImmigration Department
hk-investhkInvest Hong Kong
hk-ipdIntellectual Property Department
hk-irdInland Revenue Department
hk-isdInformation Services Department
hk-itcInnovation and Technology Commission
hk-itibInnovation, Technology and Industry Bureau
hk-jsscsJoint Secretariat for the Advisory Bodies on Civil Service and Judicial Salaries and Conditions of Service
hk-ladLegal Aid Department
hk-landsdLands Department
hk-lcsdLeisure and Cultural Services Department
hk-ldLabour 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-pscPublic Service Commission
hk-reoRegistration and Electoral Office
hk-rthkRadio Television Hong Kong
hk-rvdRating and Valuation Department
hk-sbSecurity Bureau
hk-sciocsSecretariat, Commissioner on Interception of Communications and Surveillance
hk-swdSocial Welfare Department
hk-tdTransport Department
hk-tidTrade and Industry Department
hk-tlbTransport and Logistics Bureau
hk-tryTreasury
hk-ugcUniversity Grants Committee Secretariat
hk-wfsfaaWorking Family and Student Financial Assistance Agency
hk-wsdWater Supplies Department
aahkAirport Authority Hong Kong
ccConsumer Council
centalineCentaline Property Agency Limited
cfsCentre for Food Safety
chscCommittee on Home-School Co-operation
ckfChuen Kee Ferry Limited
clpCLP Power Hong Kong Limited
compcommCompetition Commission
ctbCitybus Limited
cyberportHong Kong Cyberport Management Company Limited
dcDistrict Councils
eacElectoral Affairs Commission
ffFortune Ferry Company Limited
hkcertHong Kong Computer Emergency Response Team Coordination Centre
hkeaaHong Kong Examinations and Assessment Authority
hkelectricThe Hongkong Electric Company, Limited
hkhsHong Kong Housing Society
hkircHong Kong Internet Registration Corporation Limited
hkkfHong Kong & Kowloon Ferry Limited
hkpcHong Kong Productivity Council
hkstpHong Kong Science and Technology Parks Corporation
hktdcHong Kong Trade Development Council
hktramwaysHong Kong Tramways, Limited
hospitalHospital Authority
iaInsurance Authority
legcoLegislative Council
llbLiquor Licensing Board
mpfaMandatory Provident Fund Schemes Authority
mtrMTR Corporation Limited
nlbNew Lantao Bus Company (1973) Limited
nwfbNew World First Bus Services Limited
pcktPeng Chau Kai To Limited
rehabsocietyThe Hong Kong Society for Rehabilitation
starferryThe "Star" Ferry Company, Limited
sunferrySun Ferry Services Company Limited
towngasThe Hong Kong and China Gas Company Limited
tpdTown Planning Board
trawayTsui Wah Ferry Service (H.K.) Limited
uraUrban Renewal Authority
wkcdaWest Kowloon Cultural District Authority
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/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

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/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 format]
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.