回顧2017年3月7日(國際開放數據日),我出席了「開源香港會」舉辦的一項有關推動「開放數據」(open data) 是座談會 [1],討論關於推動智慧城市所涉及的大數據 (Big Data)及物聯網(Internet of Things,IOT)等,須從傳統只讓大眾閱覽的資料,如PDF格式,提升為電腦可讀格式資料,並支援「應用程式介面」(API),方便程式開發者處理。

四年過來,全球在開放數據上已有長足的發展,香港政府和公營機構的部份網上資訊亦開始提供JSON格式的API供開發者使用,但一般需要有基礎編碼知識才懂得使用。隨著開放數據的普及,不少國家的政府網站開始提供API (Query) Builder的應用介面,讓大家毋須學習編碼亦懂得以API形式提取資訊。譬如歐盟的Eurostat網站就有非常好用的Query Builder,有興趣的朋友可以根據我早前在Medium發表的文章[2]嘗試使用。最近香港政府的「資料一線通」網站也提供API Builder供下載API,本文嘗試使用該API Builder下載差餉物業估價署的房產價格的JSON格式數據,放進Google Colab加以處理。

根據歐盟Eurostat網站的解釋,API 字符串分為前後兩段,前段為固定部份,包括網站的URL及所提取數據的服務等,後段則屬動態部份,包括格式 (本文以JSON講解),語言,數據系列碼及相關的數據過濾要求。(圖1)

圖1 API 字符串解構(https://ec.europa.eu/eurostat/web/json-and-unicode-web-services/getting-started/rest-request)

因此,過往在編寫API字符串時均須查閱很多相關過濾選項的編碼方法,變成一大串只有電腦才看得懂的怪串,以下是本文最後會得出的API,先給大家看看是甚麼數據:

https://api.data.gov.hk/v2/filter?q=%7B%22resource%22%3A%22http%3A%2F%2Fwww.rvd.gov.hk%2Fdoc%2Fen%2Fstatistics%2Fhis_data_12.xls %22%2C%22section%22%3A1%2C%22format%22%3A%22json%22%2C%22filters%22%3A%5B%5B1%2C%22bw%22%2C%5B%221997%22%5D %5D%5D%7D

前段是比較簡單,政府的API資料網址:https://api.data.gov.hk/v2/;但後段則難以讀懂,仿佛看到差估署網址 www.rvd.gov.hk,檔案名稱 his_data_12.xls,另外我加入了過濾年份1997年起等,但若要學懂寫出這串API,可能大家都提不起興趣。

然而,通過從「資料一線通」網站 https://data.gov.hk/en-data/dataset,選擇差估署的物業市場統計資料,再選私人零售業樓宇-租金及售價指數數據 (因為現時只有這幾項有提供API),便會進入一處可使用API Builder (應用程式介面構建器) 的版面。(圖2)

圖2 差估署 API Builder 示例。資料來源:https://data.gov.hk/en-data/dataset/hk-rvd-tsinfo_rvd-property-market-statistics/resource/87045fd8-2fce-4c3e-9b5e-de3d29f640df

圖 2 顯示了通過使用應用程式介面構建 API 字符串的示例。它允許添加過濾規則(圖 2 中間右邊緣的綠色按鈕),例如年月、租金和價格等。設置過濾器後,按下獲取結果按鈕(圖 2 中左邊緣的深藍色按鈕),便會在下面自動產生一條名為應用程式介面詢問字串的 API 結果。

https://api.data.gov.hk/v2/filter?q=%7B%22resource%22%3A%22http%3A%2F%2Fwww.rvd.gov.hk%2Fdoc%2Fen%2Fstatistics%2Fhis_data_12.xls %22%2C%22section%22%3A1%2C%22format%22%3A%22json%22%2C%22filters%22%3A%5B%5B1%2C%22bw%22%2C%5B%221997%22%5D %5D%5D%7D

那麼取得這串API後可如何使用?以下是簡單在Google Colab顯示編碼讀取相關數據的示例,說明電腦可讀取數據的方法;更詳細的編碼使用數據則不在本文範圍之內,有興趣的讀者可自行在網上查找。

以下是在 Google Colab 介面以具象狀態傳輸 (REST) 從上述的 API 獲取數據的例子。若想一試但對Colab不熟識的讀者可先參考 Colaboratory 的簡介https://colab.research.google.com/notebooks/intro.ipynb?utm_source=scs-index。

首先,如圖3所示:第一步只須把該API給一個名稱,如url,透過 requests進行提取 (GET),再以 pprint便可看到電腦從API取得的數據情況,圖3中以#號開始的均為註解。

import requests  # Import the requests library

url = ('https://api.data.gov.hk/v2/filter?q=%7B%22resource%22%3A%22http%3A%2F%2Fwww.rvd.gov.hk%2Fdoc%2Fen%2Fstatistics%2Fhis_data_12.xls%22%2C%22section%22%3A1%2C%22format%22%3A%22json%22%2C%22filters%22%3A%5B%5B1%2C%22bw%22%2C%5B%221997%22%5D%5D%5D%7D')
print(url)

response = requests.get(url)  # Make a GET request to the URL

# Print status code (and associated text)
print(f"Request returned {response.status_code} : '{response.reason}'")

# Print data returned (parsing as JSON)
payload = response.json()  # Parse `response.text` into JSON

import pprint
pp = pprint.PrettyPrinter(indent=1)
pp.pprint(payload)
print(url)

圖3 Google Colab 以 requests 提取相關API的數據。

程式結果如圖4:

https://api.data.gov.hk/v2/filter?q=%7B%22resource%22%3A%22http%3A%2F%2Fwww.rvd.gov.hk%2Fdoc%2Fen%2Fstatistics%2Fhis_data_12.xls%22%2C%22section%22%3A1%2C%22format%22%3A%22json%22%2C%22filters%22%3A%5B%5B1%2C%22bw%22%2C%5B%221997%22%5D%5D%5D%7D
Request returned 200 : 'OK'
[{'售價 Prices': 150.8, '年 Year': '1997', '月 Month': '1', '租金 Rents': 119.3},
{'售價 Prices': 156.2, '年 Year': '1997', '月 Month': '2', '租金 Rents': 123.5},
{'售價 Prices': 168, '年 Year': '1997', '月 Month': '3', '租金 Rents': 120.5},
{'售價 Prices': 170.7, '年 Year': '1997', '月 Month': '4', '租金 Rents': 123},
{'售價 Prices': 182.9, '年 Year': '1997', '月 Month': '5', '租金 Rents': 122.9},
{'售價 Prices': 180, '年 Year': '1997', '月 Month': '6', '租金 Rents': 126.8},
{'售價 Prices': 181.7, '年 Year': '1997', '月 Month': '7', '租金 Rents': 124.2},
{'售價 Prices': 195.9, '年 Year': '1997', '月 Month': '8', '租金 Rents': 125.2},
{'售價 Prices': 202.6, '年 Year': '1997', '月 Month': '9', '租金 Rents': 124.5},
{'售價 Prices': 192.2, '年 Year': '1997', '月 Month': '10', '租金 Rents': 123.5},
{'售價 Prices': 181.1, '年 Year': '1997', '月 Month': '11', '租金 Rents': 123.7},
{'售價 Prices': 165.3, '年 Year': '1997', '月 Month': '12', '租金 Rents': 125.2}]

圖4 Google Colab 以 requests 提取相關API數據的結果。

那些{和:符號是JSON格式的數據分格方法,大家應該見到該API讓電腦從差估署網站自動下載了有關香港零售店舖的1997年每月售價指數和租金指數,譬如第一行顯示1997年1月的相關售價指數和租金指數分別為150.8和119.3。這樣便可利用程式進行其他數據分析和製圖等工作,譬如比較租金指數與售價指數的年度變化相關度 (如圖5),大家有興趣可以一試,答案可參考我在Github的https://github.com/Chung-collab/GREAT-LAB/blob/main/get_api.ipynb。

圖5 用API取得數據後,加上程式自動繪製擴散圖。

參考:

[1] 信報 (2017) 議員促立檔案法 加快開放數據,March 7。http://startupbeat.hkej.com/?p=42126

[2] Yiu, C.Y. (2021) Getting Data from API in Colab, Medium, June 14. https://ecyy.medium.com/getting-data-from-api-in-colab-57b9a445c791