CKAN API Development Guide

DATA.GOV.HK provides a set of API that are powered by CKAN for developers to access PSI metadata programmatically that are published on DATA.GOV.HK. This guide provides guidance and instructions on how to use the CKAN APIs.

Introduction

The DATA.GOV.HK catalogue is powered by CKAN, a powerful open source data portal software that includes a set of robust API which serves metadata of datasets. The metadata includes URLs and descriptions of datasets.

This guide is only intended to be a quick summary with examples but it is not a replacement of the CKAN API documentation which is available at

http://docs.ckan.org/en/latest/api/index.html.

Development Guide

Currently, DATA.GOV.HK only accepts specific HTTP GET requests using the following CKAN APIs.

package_list API
package_show API
group_list API
group_show API

Making an API Request

Developers can access the following CKAN API endpoints to retrieve metadata in specific languages:

https://data.gov.hk/en-data/api/3/action/[functionName?para1=value1&para2=value2&...]

For Traditional Chinese https://data.gov.hk/tc-data/api/3/action/[functionName?para1=value1&para2=value2&...]

For Simplified Chinese https://data.gov.hk/sc-data/api/3/action/[functionName?para1=value1&para2=value2&...]

Developers shall replace functionName, para* and value* with appropriate parameter strings.

The full list of available CKAN get functions and corresponding parameters can be found at http://docs.ckan.org/en/latest/api/index.html#module-ckan.logic.action.get

Concrete examples can be found in Supported APIs and Examples.

Response JSON Structure

A successful JSON response from CKAN will look similar to:


                {
                "help": "Return a list of the names of the site’s datasets (packages).\n\n …",
                "result": [
                    "centaline-centanetod-ccipropertyinfo",
                    "hk-afcd-afcdlist-pesticides-licensee-1",
                    "hk-afcd-afcdlist-pesticides-licensee-2",
                    …
                ],
                "success": true
                }

help: The documentation string which explains the function you called.

result: The returned result from the function called. The type and value of the result depend on which function you called. success: true or false indicator of whether the API call was successful.

Exceptions

A JSON response similar to the one below will return if there is an exception:


                {
                "help": "Creates a package",
                "success": false,
                "error": {
                    "message": "Access denied",
                    "__type": "Authorization Error"
                    }
                }

help: The documentation string for the function you called. success: If there was an error responding the request, it will be false. error: Details of the error responding the request.

Supported APIs and examples

DATA.GOV.HK accepts and supports the following CKAN APIs

package_list API
package_show API
group_list API
group_show API

package_list API
To get the full dataset list, the package_list API can be used: https://data.gov.hk/en-data/api/3/action/package_list

package_list API can be used with two optional parameters: limit and offset. limit (int): Sets the maximum number of dataset to be returned. offset (int): Sets the offset of the first dataset to be returned, use with limit.

For example, if we want to get the first 10 datasets starting from the 5th datasets in English, we can call https://data.gov.hk/en-data/api/3/action/package_list?limit=10&offset=5

The returned JSON will look similar to:
```
                {
                "help": "Return a list of the names of the site’s datasets (packages).\n\n …",
                "result": [
                    "centaline-centanetod-ccipropertyinfo",
                    "hk-afcd-afcdlist-pesticides-licensee-1",
                    "hk-afcd-afcdlist-pesticides-licensee-2",
                    …
                ],
                "success": true
                }
            
```
Tip: Dataset IDs returned in the result array can be used in other APIs for further processing.

package_show API

To get the details of a particular dataset, the package_show API can be used: https://data.gov.hk/en-data/api/3/action/package_show?id=[dataset_id]

Note: the parameter id is mandatory for this function.

For example, to show metadata of hk-td-tis_2-traffic-snapshot-images in English: https://data.gov.hk/en-data/api/3/action/package_show?id=hk-td-tis_2-traffic-snapshot-images

The returned JSON will look similar to:


                {
                "help": "Return the metadata of a dataset (package) and its resources.\n\n …",
                "success": true,
                "result": {
                    "license_title": null,
                    "maintainer": "TD General Enquiry Hotline",
                     …
                    "resources": [
                        {
                            "share_id": "08e6c…",
                            "description": "CCTV Camera Locations (English)",
                            "state": "active",
                            …
                        },  …
                    ], …
                }
                }

group_list API

To list all data categories available, the group_list API can be used.

For example, to list all data categories in English: https://data.gov.hk/en-data/api/3/action/group_list

The returned JSON will look similar to:



                {
                "help": "Return a list of the names of the site’s groups.\n\n …,
                "success": true,
                "result": [
                     "city-management",
                     "climate-and-weather",
                     "commerce-and-industry",
                     "development",
                     "education",
                     "employment-and-labour",
                     "environment",
                      …
                 ]
                }

group_show API

To list all datasets available under a specific category, the group_show API can be used.

For example, to list all dataset under the the environment category in Simplified Chinese: https://data.gov.hk/sc-data/api/3/action/group_show?id=[group_id]

The returned JSON will look similar to:



                {
                "help": "Return the details of a group.\n\n …",
                "success": true,
                "result": {
                     …
                    "packages": [
                        {
                            "license_title": null,
                            "maintainer": "一般查询 (电话) 或 咪嘥嘢 (电邮)",
                            "state": "active",
                            …
                        },  …
                    ], …
                }
                }