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.
  1. package_list API
  2. package_show API
  3. group_list API
  4. 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
  1. package_list API
  2. package_show API
  3. group_list API
  4. 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",
                                …
                            },  …
                        ], …
                    }
                    }
                

Access to save data on the browser is disabled, some functions may not be available.

Please enable the access to unlock the full functionality of the website.