CKAN 应用程式介面开发指南

「资料一线通」提供一套由CKAN开发的应用程式介面，以供开发者以程式访问在「资料一线通」上发布的公共资料的元数据。本开发指南提供如何使用CKAN应用程式介面的指导和说明。

引言

「资料一线通」的数据集目录背后使用了一个专为资料一线通的强大开源软件CKAN。它包含了一些可靠的应用程式介面供开发者使用，这些应用程式介面会回传数据集的诠释资料 (Metadata)，例如相关数据集的网址和描述等等。

本篇开发指南旨在简单归纳CKAN应用程式介面的使用方法，方便开发者参考。它并不能完全取代CKAN的官方文件:

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

开发指南

「资料一线通」目前只接受使用以下特定的 HTTP GET CKAN应用程式介面请求。

package_list 应用程式介面
package_show 应用程式介面
group_list 应用程式介面
group_show 应用程式介面

CKAN 应用程式介面请求

开发者可以透过以下方式向CKAN应用程式介面作出请求，取得特定语言网站中的资料集诠释资料。

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

繁体中文https://data.gov.hk/tc-data/api/3/action/[functionName?para1=value1&para2=value2&...]

简体中文https://data.gov.hk/sc-data/api/3/action/[functionName?para1=value1&para2=value2&...]

开发者需自行把functionName，para* 和 value* 转换成合适的CKAN应用程式介面功能和参数。

CKAN提供的所有应用程式介面功能及参数列于http://docs.ckan.org/en/latest/api/index.html#module-ckan.logic.action.get

完整的使用例子可参考支援的CKAN应用程式介面功能及示范。

回应的JSON结构

以下是CKAN应用程式介面成功请求时所回传的例子:


                {
                "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: CKAN应用程式介面中对于该请求所使用的应用程式介面功能描述。

result: 对于该请求的回传结果。结果中的资料类别及值会因不同的应用程式介面功能而异。 success: true 或 false，代表该请求成功与否。

错误

以下是出现错误时应用程式介面所回传的范例:


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

help: CKAN档案中对于该要求所使用的应用程式介面功能描述。 success: 如果该请求产生了错误，回传的值必定为 false。 error: 该请求错误的详细资料。

支援的CKAN应用程式介面功能及示范

「资料一线通」接受并支援以下CKAN应用程式介面

package_list 应用程式介面
package_show 应用程式介面
group_list 应用程式介面
group_show 应用程式介面

package_list 应用程式介面
开发者可以透过package_list 应用程式介面取得完整的数据集目录: https://data.gov.hk/tc-data/api/3/action/package_list

package_list 应用程式介面支援两个可选的参数: limit 和offset。 limit (int): 指定最多可回传的数据集数量。 offset (int): 指定第一个数据集的位置，须与limit一同使用。

例如，当我们想取得英文网站中的第5个至第14个资料集(索引头为0)，可作以下请求: https://data.gov.hk/en-data/api/3/action/package_list?limit=10&offset=5

以下是应用程式介面所回传的例子:
```
                {
                "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
                }
            
```
小提示: 回传的资料集ID可用于请求其它应用程式介面，以作进一步的处理。

package_show 应用程式介面

开发者可以透过package_show 应用程式介面取得特定资料集的诠释资料: https://data.gov.hk/tc-data/api/3/action/package_show?id=[dataset_id]

请留意参数id 为必要参数，代表想取得的特定资料集。

例如，当我们想取得英文网站中资料集id为hk-td-tis_2-traffic-snapshot-images 的诠释资料，可作以下请求: https://data.gov.hk/en-data/api/3/action/package_show?id=hk-td-tis_2-traffic-snapshot-images

以下是应用程式介面所回传的例子:


                {
                "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 应用程式介面

开发者可以透过 group_list 应用程式介面取得所有资料集的分类。

例如，要取得英文网站中的所有分类, 可作以下请求: https://data.gov.hk/en-data/api/3/action/group_list

以下是应用程式介面所回传的例子:



                {
                "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 应用程式介面

开发者可以透过 group_show 应用程式介面取得特定分类的资料集。

例如，当我们想取得简体中文网站中所有分类为「environment」的资料集及其诠释资料，可作以下请求: https://data.gov.hk/sc-data/api/3/action/group_show?id=[group_id]

以下是应用程式介面所回传的例子:



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