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

在瀏覽器上存儲數據的權限被禁用,部分功能可能無法正常運作。

為了完整使用網站的功能,請啟用存取權限。