CKAN 应用程式介面开发指南

「开放数据平台」提供一套由CKAN开发的应用程式介面,以供开发者以程式访问在「开放数据平台」上发布的开放数据的元数据。 本开发指南提供如何使用CKAN应用程式介面的指导和说明。
引言
「开放数据平台」的数据集目录背后使用了一个专为开放数据平台的强大开源软件CKAN。它包含了一些可靠的应用程式介面 供开发者使用,这些应用程式介面会回传数据集的诠释资料 (Metadata),例如相关数据集的网址和描述等等。

本篇开发指南旨在简单归纳CKAN应用程式介面的使用方法,方便开发者参考。它并不能完全取代CKAN的官方文件:
http://docs.ckan.org/en/latest/api/index.html

开发指南
「开放数据平台」目前只接受使用以下特定的 HTTP GET CKAN应用程式介面请求。
  1. package_list 应用程式介面
  2. package_show 应用程式介面
  3. group_list 应用程式介面
  4. 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&...]

开发者需自行把functionNamepara*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应用程式介面
  1. package_list 应用程式介面
  2. package_show 应用程式介面
  3. group_list 应用程式介面
  4. group_show 应用程式介面





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

    package_list 应用程式介面支援两个可选的参数: limitoffsetlimit (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",
                                …
                            },  …
                        ], …
                    }
                    }
                

在浏览器上存储数据的权限被禁用,部分功能可能无法正常运作。

为了完整使用网站的功能,请启用存取权限。