搜尋地點

search_places 工具可讓 LLM 根據自然語言查詢，在 Google 地圖上尋找地點。工具會傳回 AI 生成的相符地點摘要。對於摘要引用的每個地點，系統也會傳回地點 ID、經緯度座標、Google 地圖連結和屬性。

您可以透過 MCP 伺服器或 searchText REST 方法呼叫 search_places。本頁面說明要求選項 (包括專業版選項)、回應內容，以及要求的計費方式。如需完整結構定義，請參閱 search_places MCP 參考資料和 searchText REST 參考資料。

要求選項

LLM 呼叫工具時，會根據使用者要求和工具說明設定這些選項。您可以透過自己的指令，影響模型使用的選項；請參閱「控管 Pro 用量」。

下表說明 search_places 的要求選項：

選項	說明
`text_query`	必填。搜尋查詢，例如 `coffee shops near Golden Gate Park`。查詢必須包含足夠的位置資訊，才能明確指出地點，否則要求必須包含 `location_bias`。
`location_bias`	圓形 (`center` 和選用的 `radius_meters`，上限 50,000 公尺)，用於調整結果。如果 `text_query` 指定明確位置，系統會改用該位置。
`language_code`	摘要的語言，例如 `en` 或 `ja`。預設為英文。
`region_code`	使用者的 CLDR 區域代碼，例如 `US`。會影響特定區域的地點名稱，並可能根據適用法律影響結果。
`page_size`	要傳回的地點數量上限。預設值為 5。6 到 10 的值為 Pro 選項。如果值大於 10，系統會傳回 `INVALID_ARGUMENT` 錯誤。服務傳回的地點數量可能會少於要求數量。
`include_extended_details`	當 `true` 時，摘要會包含擴充地點詳細資料。這是 Pro 選項。預設為 `false`。

Pro 選項

其中兩個選項會選取 Maps Grounding Pro SKU。使用其中一項或兩項功能的要求，會以 Pro SKU 計費：

Pro 選項	適用時機
`include_extended_details`已設在`true`	使用者的要求需要延伸 Place Details，例如評論洞察、菜單亮點、氣氛或訪客提示。
`page_size` (從 6 點提高至 10 點)	使用者想比較超過 5 個地點。

如果要求未使用上述任一選項 (包括 page_size 為 1 到 5 的要求)，則會依 Essentials SKU 計費。

擴充地點詳細資料

如果使用者的要求需要定性洞察、即時條件或特殊屬性，請將 include_extended_details 設為 true，例如：

評論者意見：根據評論、顧客觀感和意見回饋提供的洞察資料。
特定餐點：菜單品項、料理、特色餐點、飲料或商家特色。
氣氛：室內裝潢、美感、氛圍或情調。
實用的訪客提示：是否需要預約、現場候位政策、等待時間、地點繁忙程度、停車和設施。
鄰近程度：當使用者詢問附近或最近的地點時，與查詢位置或 location_bias 中心的距離或行程時間。

摘要中的洞察資訊取決於查詢，以及每個地點的可用資料。並非每則回覆都會顯示所有類型的洞察資訊。

如要進行標準搜尋 (菜餚或商店類型、地址、聯絡資訊、營業時間和標準設施)，請保留 false (預設值)。如果要求包含詳細資料，則需要較長時間才能完成。

擴充詳細資料不會變更回應結構。如果沒有，摘要會用一兩句話描述每個地點。有了這些模型，每個地點都能獲得更長的說明，並利用更多 Google 地圖資料，包括評論中的洞察資訊。兩個 SKU 的結構化 places 項目相同。

範例

下列 MCP 要求會要求最多 8 個地點，並提供詳細資訊。並依 Pro SKU 計費：

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

以下範例會將相同要求傳送至 searchText REST 方法：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

將 API_KEY 替換為您的 API 金鑰。

如果沒有詳細資料，摘要會用一兩句話描述每個地點：

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) 燭光搖曳的溫馨用餐室，評論者認為氣氛浪漫，但週末時較為吵雜。招牌菜包括肉醬義大利寬麵、布拉塔起司和提拉米蘇。建議事先預約，週五和週六晚上現場候位可能需要等候 30 到 45 分鐘，且路邊停車位有限。

回應

回應包含下列欄位：

summary：搜尋結果的自然語言摘要。其中可能包含從零開始的引用，例如 [0]，對應至 places 中的項目。
places[]：摘要中提及的地點。每個地點都包含：
- place：地點的資源名稱，格式為 places/{id}。
- id：地點 ID。您可以搭配其他 Google Maps Platform API 使用，例如在地圖上顯示地點。
- location：地點的經緯度座標。
- googleMapsLinks：地點 (placeUrl)、路線 (directionsUrl)、評論 (reviewsUrl)、相片 (photosUrl) 和撰寫評論 (writeAReviewUrl) 的 Google 地圖連結。
- attribution：必須與地點一併顯示的作者資訊。請參閱出處規定。
contentToken：代理式資料視覺化符記 (預先發布版)，可讓您使用 Places UI Kit 顯示回覆中的地點，不需額外付費。如果回應包含至少一個地點，就會傳回這個值。

無論是 SKU、MCP 還是 REST，回應的結構都相同。如需欄位詳細資料，請參閱 search_places 參考資料。

計費和配額

每個 search_places 要求都是一個計費事件：

如果要求未使用任何 Pro 選項，則會依 Maps Grounding Essentials SKU 計費。
使用 Pro 選項的要求會依 Maps Grounding Pro SKU 計費。在單一要求中同時使用這兩個選項，費用不會改變。如要瞭解 Pro 定價，請參閱「比較 Essentials、Pro 和利用 Google 地圖建立基準」。

如果您使用 Places UI Kit 顯示 search_places 回應中的地點，可以使用代理資料視覺化權杖 (預先發布版)，這樣系統就不會對這些 Places UI Kit 要求收費。

search_places 配額為每項專案每分鐘 300 次查詢，由兩個 SKU 共用。如需定價資訊，請參閱主要價目表和印度價目表。