查詢・ Geocoding

Geocoding

地址與座標互相轉換。
手上是一行地址就換成座標畫到圖上，手上是一組座標就換回一個看得懂的門牌 —— 兩個方向走的是同一條端點。

看 API 文件看 Places

方向: 2
回應語言: zh-TW
請求: GET

正向・ Address → 座標逆向・ LatLng → 地址

Address台北市中正區羅斯福路二段100號

LatLng25.026747, 121.522371

同一條端點的兩個方向，地址與座標為實際回應。

一條端點，兩個方向

正向與逆向為同一支 API。同一個 GET /maps/api/geocode/json，差別只在你帶哪一個參數：

帶 Address ——「台北市中正區羅斯福路二段100號」換成 25.026747, 121.522371。
帶 LatLng —— 把 GPS 回報、使用者在圖上按的那一點換成一行看得懂的地址。

兩個都帶的話以 Address 為準。Language目前只接受 zh-TW，不帶預設為中文。

地址本身常常就是個資，有些場域不能送出內網。Geocoding 另外有地端部署版本 —— 服務與圖資都裝在客戶自己的機房，解析全程不出去，詳見 Self-Hosted。

回應結果

回應不是只有一組座標。地址被拆成層級、定位的精度被標出來，還附一個 viewport —— 把地圖套上去就是剛好框住這個地點的視野，不必自己決定 zoom。

formattedAddress台北市中正區羅斯福路二段100號
geometry.location25.026747, 121.522371
geometry.locationTypeROOFTOP
geometry.viewport25.025398, 121.521022 ─ 25.028096, 121.523720
addressComponents台北市・中正區・羅斯福路二段・ 100 ・ 100404
typesstreet_address

實際回應（查「台北市中正區羅斯福路二段100號」）
geometry.locationType 是定位的精準程度、addressComponents 則是拆好的地址層級。

addressComponents 每一項都帶 types，要拿行政區或郵遞區號填表單時照 types 取就好，不用自己切字串。

解析精度

地址解析一定會有解不到門牌的時候，geometry.locationType 就是這個欄位，實測到三種值：

ROOFTOP

定位到門牌

輸入是完整門牌時回這個，座標落在那一棟上。實測「台北市信義區信義路五段7號」與「台北市中正區羅斯福路二段100號」都是這一級。

RANGE_INTERPOLATED

在路段上內插

只給到路段、沒有門牌號時回這個。座標是沿著那一段路推算出來的位置，拿來當「這條路上」沒問題，當成某一戶就不行。

APPROXIMATE

概略位置

只對得上行政區層級時回這個。實測把地標名稱丟進來也會落在這一級 —— 那通常代表你要的其實不是地址解析。

Geocode Advanced

同一區還有一支 GET /maps/api/GeocodeAdvanced。它只吃 Address（沒有逆向），但多回三樣東西：正規化後的地址、定位層級 level，以及門牌的出入口座標entryPoint。

Address北市羅斯福路2段100號

normalizedAddesss台北市羅斯福路二段100號

levelAddesss台北市中正區羅斯福路二段100號

level 1定位到門牌

Address台北市中正區羅斯福路二段

normalizedAddesss台北市中正區羅斯福路二段

levelAddesss台北市中正區羅斯福路二段

level 5定位到路段

Address台北市中正區黎明里

normalizedAddesss台北市中正區黎明里

levelAddesss台北市中正區黎明里

level 6定位到村里

Address台北市

normalizedAddesss台北市

levelAddesss台北市

level 8定位到縣市

四組都是實際回應。數字越小，定位到的層級越細。

這不是地點搜尋

Geocoding 吃的是地址，不是地點名稱。實測把「台北101」丟進去，回的是 台北市、APPROXIMATE —— 它沒有解不開，只是退到了行政區層級，看起來像成功其實不是你要的。

手上是「台北市信義區信義路五段7號」這種地址 → Geocoding。
手上是「台北101」「這附近的拉麵」這種說法 → Places，它回的每一筆也都帶座標。
使用者還在搜尋框裡打字 → Autocomplete。

串接 API

output 走路徑（填 json）、Key 必填，Address 與 LatLng 擇一。

# 正向：地址 → 座標
curl -sS -G "https://kwmap.localking.com.tw/maps/api/geocode/json" \
  --data-urlencode "Address=台北市中正區羅斯福路二段100號" \
  --data-urlencode "Key=<your-key>" \
  -H "Ocp-Apim-Subscription-Key: <subscription-key>"

# 逆向：座標 → 地址
curl -sS -G "https://kwmap.localking.com.tw/maps/api/geocode/json" \
  --data-urlencode "LatLng=25.026747,121.522371" \
  --data-urlencode "Key=<your-key>" \
  -H "Ocp-Apim-Subscription-Key: <subscription-key>"

完整參數與回應結構見 Geocoding 與 Geocode Advanced 的 API 文件。