查詢・ Autocomplete

Autocomplete

使用者還在打字時就給建議。每按一個鍵打一次，回一批預測。地點、地址與興趣點都在裡面，並且附帶高亮命中的字。

看 API 文件看 Places

可指定類型: 5
回應時機: 每一鍵
請求: GET

京站汽

京站台北市大同區承德路一段1號
京站汽車停車場台北市大同區承德路一段1號B4樓
屯京拉麵中山店台北市中山區中山北路一段141號
3 筆預測

京站台北市大同區承德路一段1號
京站汽車停車場台北市大同區承德路一段1號B4樓
2 筆預測

京站汽車停車場台北市大同區承德路一段1號B4樓
1 筆預測

地點名稱與地址為實際查詢結果；預測的排序與筆數為示意。

邊打邊回

Input 帶的是使用者當下打到一半的字，不是完整的地名。每多一個字就少一批預測，直到剩下他要的那一個。

這意味著呼叫頻率很高。實務上會在輸入框加入防抖（大約 150–300 毫秒），並在使用者按下 Enter 或選定之後停止呼叫；同一次搜尋的所有請求帶同一個 SessionToken，計費才會以一次搜尋計算。

回應直接對得上畫面

預測不是只回一個字串。命中的位置、地點名稱與街道地址是分開回的，所以標粗、排兩行這些事不必自己切字串。

畫出來的樣子

屯京拉麵中山店台北市中山區中山北路一段141號

輸入「京」

回應提供的資訊

matched_substrings[{ offset: 1, length: 1 }]命中的是第 2 個字，不是開頭 —— 所以要回位置，前端才知道該把哪一段標粗。
structured_formatting.main_text屯京拉麵中山店地點名稱，單獨一個欄位。
structured_formatting.secondary_text台北市中山區中山北路一段141號街道地址，跟名稱分開回 —— 兩行排版不必自己切字串。
place_idQP9MBC使用者選了之後，用它去 Place Details 取完整資料。

名稱、地址與 place_id 為實際查詢結果；offset 依名稱與輸入計算。

選定之後接 Place Details

Autocomplete 的回應較簡潔，因為它要在每一次按鍵之間回完。電話、營業時間、照片與網站要等使用者真的選了，再拿 place_id 打一次 Place Details。

SessionToken

Place/Autocomplete

邊打邊回

屯京拉麵中山店
place_id: QP9MBC

每按一鍵打一次，回得很簡潔

使用者點選

選定一筆

拿著 place_id

不必把使用者打的字再送一次

Place/Details

取完整資料

02-25625066
台北市中山區中山北路一段141號
opening_hours ・ website ・ photos

整段流程只打這一次

三步帶同一個 SessionToken 才算同一次搜尋。欄位值為實際查詢結果。

限定範圍與類型

Location 讓該座標附近的地點優先出現，Radius 再給一個範圍。Types 可以用 | 串接，最多五種。

Types=book_store|cafe|restaurant：比 TextSearch 的 Type 寬鬆，那邊一次只能指定一種。
Location 與 Radius 是優先而不是篩選，範圍外的地點仍可能出現。要硬性限制得自己拿回傳座標再過濾。
Language 目前只支援 zh-TW。

完整類型清單見 Type List。

跟 TextSearch 的差別

兩支都是拿文字換地點，差別在使用者處於哪個時刻：還在打用 Autocomplete，已送出用 TextSearch。

Autocomplete：每一鍵打一次，回的是預測；要完整資料得再接 Place Details。
TextSearch：送出後打一次，一次最多 20 筆，每一筆就帶座標、地址與 kw_extra，可以直接畫在地圖上。
類型：Autocomplete 的 Types 最多五種， TextSearch 的 Type 只能一種。

一個搜尋框通常兩支都要：打字時 Autocomplete，使用者不選建議直接送出時才是 Places。

串接 API

REST 端點是 GET /maps/api/Place/Autocomplete/json。Input 與 Key 是必填。

curl -sS -G "https://kwmap.localking.com.tw/maps/api/Place/Autocomplete/json" \
  --data-urlencode "Input=京站" \
  --data-urlencode "Location=25.0478,121.5170" \
  --data-urlencode "Types=shopping_mall|parking" \
  --data-urlencode "SessionToken=<uuid-v4>" \
  --data-urlencode "Key=<your-key>" \
  -H "Ocp-Apim-Subscription-Key: <subscription-key>"

完整參數與回應結構見 API 文件。