我們建立「防災地方誌」平台,除了希望這裡成為獲知與分享地方防災相關資訊的最佳平台,更希望這裡成為可以支援其它許多地方防災應用的基礎建設。如同開放街圖(OpenStreetMap)做為開放的地理資訊平台,我們希望防災地方誌成為讓所有社區交流災害相關知識的平台,內容可以是關於:地點、人、鄰里組織⋯⋯都可以!

我們也期待防災地方誌能成為地方防災知識的 API。


概要

防災地方誌提供一組 RESTful、可讀取與寫入資料、俱備地理資訊處理功能的應用程式介面(API)。任何人都可以透過 API 利用 HTTP GET 請求讀取資料。要寫入資料(利用 HTTP POSTPUTPATCHDELETE 請求)必須取得 API key

API 的前導網址為 https://lowiki.tw/api/v4/

用瀏覽器開啟 API 前導網址 可以看到 API 功能概覽。

我們假設你對於 REST API 的使用方式多少有些認識。以一般的標準 HTTP 程式庫,即可利用 API 來讀取與寫入網站資料。

分頁

從 API 讀取的資料,可以用 nextprevious 網址讀取下一頁資料。你可以用 limit 參數,指定每一頁包含的資料數量(最多 100 筆)。

過濾結果

從 API 讀取的資料,可以用過濾欄位(filter field)縮小資料的範圍。用瀏覽器開啟 API 網址可以看到 API 可以使用的過濾欄位說明,或是利用 OPTIONS 請求。所有欄位值都必須以 URL 格式編碼。

只取用部份的欄位

透過網路讀取資料時,有時適合只從查詢結果中取得一部份需要用的欄位。你可以用 fields 參數指定只取用部份的欄位。參數值應為要取用的欄位名稱,以逗號分隔。注意這僅限於 GET 請求可以使用。

對結果排序

部份查詢結果,可以用 ordered 參數指定排序條件。可用的 ordering 參數值,可以用瀏覽器開啟 API 網址,或用 OPTIONS 請求查看。

標準查詢方式

部份欄位可以用標準查詢方式,進一步過濾資料。以下這些過濾條件的欄位值,依指定查詢的欄位資料型別而有所不同。

部份欄位容許以下的過濾條件:

  • exact -- 完全相符。
  • iexact -- 忽略大小寫,此外完全相符。
  • contains -- 包含子字串。
  • icontains -- 忽略大小寫,包含子字串。
  • gt -- 大於。
  • gte -- 大於或等於。
  • lt -- 小於。
  • lte -- 小於或等於。
  • startswith -- 查詢字串開頭。
  • istartswith -- 忽略大小寫,查詢字串開頭。
  • endswith -- 查詢字串結尾。
  • iendswith -- 忽略大小寫,查詢字串結尾。
  • isnull -- 是否為 NULL(可為 TrueFalse)。
  • regex -- 正規表達式。
  • iregex -- 忽略大小寫,正規表達式。

有些查詢方式不支援所有欄位。例如,icontains 查詢對於時間型別的欄位沒有意義。

範例

列出所有名稱以 "doge" 開頭的使用者,忽略大小寫:

/api/users/?username__istartswith=doge

列出所有在 2014-01-16T00:00:00.0 之後發生的頁面編修歷史:

/api/pages_history/?history_date__lt=2014-01-16T00:00:00.0

地理資訊查詢方式

部份欄位可以用地理資訊查詢方式,進一步過濾資料。

以下這些過濾條件的欄位值,應為 GeoJSON geometry object 格式。

部份欄位容許以下的過濾條件:

  • bbcontains -- 查詢條件幾何外框的邊界框(bounding box)完全包含資料幾何外框的邊界框。
  • bboverlaps -- 查詢條件幾何外框的邊界框與資料幾何外框的邊界框重疊。
  • contained -- 查詢條件幾何外框完全被資料幾何外框所包含。
  • contains -- 查詢條件幾何包含資料幾何外框。
  • contains_properly -- 資料幾何外框與查詢條件幾何外框內部有交集,但與邊界或外部沒有交集。
  • coveredby -- 查詢條件裡的點位全數落在資料幾何外框之內。
  • covers -- 資料幾何外框裡的點位全數落在查詢條件幾何外框之內。
  • crosses -- 查詢條件幾何外框在空間中通過資料幾何外框。
  • disjoint -- 查詢條件幾何外框在空間中分離於資料幾何外框。
  • equals -- 測試相等。

  • exact, same_as -- 測試相等。
  • intersects -- 查詢條件幾何外框與資料幾何外框在空間中有交集。
  • overlaps
  • touches -- 查詢條件幾何外框在空間中接觸資料幾何外框。
  • within -- 查詢條件幾何外框在空間中內含於資料幾何外框。
  • left -- 查詢條件幾何外框的邊界框位於資料幾何外框的邊界框的左側。
  • right -- 查詢條件幾何外框的邊界框位於資料幾何外框的邊界框的右側。
  • overlaps_left -- 查詢條件幾何外框的邊界框重疊於或位於資料幾何外框的邊界框的左側。
  • overlaps_right -- 查詢條件幾何外框的邊界框重疊於或位於資料幾何外框的邊界框的右側。
  • overlaps_above -- 查詢條件幾何外框的邊界框重疊於或位於資料幾何外框的邊界框的上方。
  • overlaps_below -- 查詢條件幾何外框的邊界框重疊於或位於資料幾何外框的邊界框的下方。
  • strictly_above -- 查詢條件幾何外框的邊界框位於資料幾何外框的邊界框的上方。
  • strictly_below -- 查詢條件幾何外框的邊界框位於資料幾何外框的邊界框的下方。
  • isnull --可為 TrueFalse。

範例

列出所有含有一個以上幾何物件在指定區域內的地圖物件:

/api/maps/?polys__within={ "type": "Polygon", "coordinates": [ [ [ -117.22412109375, 24.347096633808512 ], [ -117.22412109375, 32.43561304116276 ], [ -102.9638671875, 32.43561304116276 ], [ -102.9638671875, 24.347096633808512 ], [ -117.22412109375, 24.347096633808512 ] ] ] }

列出所有含有一個以上幾何物件包含指定座標於其中的地圖物件:

/api/maps/?polys__contains={ "type": "Point", "coordinates": [ -122.44674682617188, 37.76745803822967 ] }

列出所有含有一個以上點位於指定區域內的地圖物件:

/api/maps/?points__within={ "type": "Polygon", "coordinates": [ [ [ -122.51575469970703, 37.78781006166096 ], [ -122.50202178955078, 37.708541298593325 ], [ -122.37911224365234, 37.70881291183666 ], [ -122.37808227539061, 37.761487048570935 ], [ -122.3818588256836, 37.790794553924414 ], [ -122.40726470947266, 37.81493737606794 ], [ -122.47764587402344, 37.81059767530207 ], [ -122.51575469970703, 37.78781006166096 ] ] ] }

編修記錄

所有可編修的資料(頁面、地圖等等)都有相對應的編修記錄可以查詢。

history_type 的欄位值可以是:

  • 0 - 新增
  • 1 - 更新
  • 2 - 刪除
  • 3 - 連帶刪除
  • 4 - 回復
  • 5 - 回復新增
  • 6 - 回復刪除
  • 7 - 回復連帶刪除
  • 8 - 連帶回復

透過 API 上傳檔案

上傳檔案,必須對 /files/ 資源發送 POST/ PUT /PATCH 請求。發送檔案時,必須用 multipart/form-data 做為請求類型。檔案應以 file 為表單屬性發送,檔案名稱應以 name 為屬性發送。