CKAN 應用程式介面開發指南

「開放數據平台」提供一套由CKAN開發的應用程式介面，以供開發者以程式訪問在「開放數據平台」上發布的開放數據的元數據。本開發指南提供如何使用CKAN應用程式介面的指導和說明。

引言

「開放數據平台」的數據集目錄背後使用了一個專為開放數據平台的強大開源軟件CKAN。它包含了一些可靠的應用程式介面供開發者使用，這些應用程式介面會回傳數據集的詮釋資料 (Metadata)，例如相關數據集的網址和描述等等。

本篇開發指南旨在簡單歸納CKAN應用程式介面的使用方法，方便開發者參考。它並不能完全取代CKAN的官方文件:

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

開發指南

「開放數據平台」目前只接受使用以下特定的 HTTP GET CKAN應用程式介面請求。

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_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",
                            …
                        },  …
                    ], …
                }
                }