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. :
|
No | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
provider |
Provider ID, e.g.: hk-ogcio. 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 |
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 |
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.