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.
| No | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| provider | Provider ID, e.g.: hk-dpo. The full list of the Provider ID is listed below:
| 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:
| 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:
- dataset name and resource name - if
orderis bydataset-en,dataset-tcordataset-sc. - resource name - if
orderis byresource-en,resource-tcorresource-sc. - URL, if
orderis byurl.
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)
| 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, eq - is equal to [ “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): 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) asc - in ascending order | No |
| format | string | Output Format: CSV (default) | 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.