Introduction

感謝您使用 台灣圖霸 「尊爵版」: 最適合房仲業不動產物件的學區查詢 API！

讓您可以透過給定地理經緯度座標，直接取回該座標所屬的國中、國小學區。

台灣圖霸 尊爵版房仲業學區查詢 API -- 簡單、方便、好用、準確。

Notation

左右鍵符號 (大於、小於符號, 也就是 < >) 所描述的是一個變數 (variable) 的 formal parameter 形式。本文件底下若提及參數部分，使用到此表示法時，請讀者將之代換成實際的內容 (也就是代換為 actual parameter，並且，不留下 < > 符號)。例如, https://api.map8.zone/find?keyword=<關鍵詞> 若實際關鍵詞為 taiwan，則實際呼叫時，應代換為 https://api.map8.zone/find?keyword=taiwan。
位於 API 欄位內格式的 <參數>，為標準的 URL 之 query string 格式編碼 (i.e., name=value 以 URL % 編碼, 並以 & 連接)
除非另有指定，否則，地理經緯度座標 (lat 或 latitude 均指經度，lng 或 longitude 均指緯度) 以 WGS84 / EPSG:4326 為地理座標系統

Version

v1.0_2019-11-12 (the present document)
舊版
- (不再支援) (尚無。)

API Index

Map8 Premium 尊爵版

[Housing] School Districts API
- 查詢一座標所屬之學區

尊爵版 : [Housing] School Districts API

Syntax

https://api.map8.zone/v2/premium/housing/schooldistricts?key=<您的 key>&location=<緯度>,<經度>&kind=<國中 | 國小>

Example : 查詢座標 24.868242, 121.206504 所屬之國小學區

curl -X GET "https://api.map8.zone/v2/premium/housing/schooldistricts?location=24.868242%2C121.206504&kind=國小&key=<您的 key>"

{
  "html_attribution": [
    "台灣圖霸",
    "研鼎智能",
    "PAPAGO!"
  ],
  "results": [
    {
      "place_id": "NzYqAQYDRxkHXF1TEjlZU1E6Ly5LVBADPA4Oc1xdPk4NSy1HWGsCEg==", 
      "city": "台南市",
      "town": "龍潭區",
      "name": "龍潭國小",
      "kind": "國小"
    }
  ],
  "status": "OK"
}

功能 : 查詢所給定的地理經緯度座標之所屬學區 (國中、國小)

API :
- https://api.map8.zone/v2/premium/housing/schooldistricts?<參數>
Synopsis
- <參數>
  - key
    - 必要參數，請帶進您的 key
  - location
    - 必要參數，要求系統依據給定的地理座標為搜尋中心點。格式為 <緯度>,<經度>，分別為緯度與經度
  - kind
    - 選擇性參數。可為 國小 或 國中。

Response

Status code : 200 OK

表示成功完成您的 request

Response Message Body

type: application/json

{
   "html_attributions" : [    // 您必須向使用者表彰之本 API 所屬的圖資版權資訊
       "台灣圖霸", 
       "研鼎智能", 
       "PAPAGO!"
   ],
   "results" : [              // `搜尋結果` 陣列
      {
         "place_id" : <String>,  // 搜尋結果之學校於台灣圖霸系統內的地點 ID。您可以藉此再呼叫 `Place Details API` 來取得該學校進一步的地點詳細資料
         "city" : <String>,      // 搜尋結果之學校所屬的城市 (例如 "台北市")
         "town" : <String>,      // 搜尋結果之學校所屬的行政區 (例如 "內湖區")
         "name" : <String>,      // 搜尋結果之學校 (學區) 名稱
         "kind" : <String>,      // 搜尋結果之學區為 `國中` 或 `國小`
     },
     ... (more results) ...
   ],
   "status" : <String>        // Status Code
}

上述每一筆搜尋結果內的各欄位, 若無值, 仍一律回傳, 但帶空值
results 陣列帶回本次搜尋的查詢結果
place_id 即為該學區 (學校) 於台灣圖霸系統內的地點 ID。您可以藉此再呼叫台灣圖霸 Map8 的 Place Details API 來取得該學校進一步的地點詳細資料。

Status code : 400 Bad Request
- 表示您的 request 系統偵測到有錯誤而無法完成您的要求。通常是給入的參數多了或少了，或是格式有錯誤，或必要參數卻沒給，等等
- Response Message Body
  - Content-type: application/json
```
{
    "status" : <String>     // Status Code
}
```
參見 HTTP Status Code 一節說明本 API 回傳值之一般通則
參見 "status" 欄位一節說明 "status" 欄位的一般性意義

back to index

台灣圖霸感謝您的支持與愛護！

有任何疑問，或是指教，都非常歡迎您找我們詢問。

非常感謝！

https://map8.zone

HTTP Status Code

以上 API，可能回傳的 HTTP status code 如后 :

Error Code	意義
400	Bad Request -- 表示您的 requset 解析有誤。通常是給入的參數多了或少了，或是格式有錯誤，或必要參數卻沒給，等等
401	Unauthorized -- 表示您未給定您的 key，或是您給的 key 並非有效。請跟我們聯絡
503	Service Unavailable -- 表示您的 request 已經超出與我們約定的 QoS (服務品質) 等級。通常過一會兒 (QoS 上限解除) 再重發一次即可成功。如果持續發生，請跟我們聯絡

"status" 欄位

以上 API，可能回傳之 status 欄位的意義為 :

`status` 值	意義
`OK`	無發生任何錯誤；該地點被成功偵測，並且至少回傳一則結果
`ZERO_RESULTS`	表示搜尋雖然完成，但未得到任何有效結果。此狀況譬如可能發生在您對本 API 發出的 request 所給定的中心座標在一個不適當的地點
`OVER_QUERY_LIMIT`	表示您已經超出您的配額。請跟我們聯絡
`REQUEST_DENIED`	表示您的 request 無法進行；一般來說是您未給定您的 key，或是您給的 key 並非有效。請跟我們聯絡
`INVALID_REQUEST`	表示您的 requset 解析有誤。通常是給入的參數多了或少了，或是格式有錯誤，或必要參數卻沒給，等等
`UNKNOWN_ERROR`	表示是我們的伺服器端的錯誤；再重試一次可能就會成功。如果持續發生此問題，請跟我們聯絡