搜尋地點

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

本頁面說明要求選項 (包括 Pro 選項)、回應內容，以及要求的計費方式。如需完整的工具結構定義，請參閱 search_places 參考資料。

要求選項

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

選項	說明
`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 選項

有兩個選項可選取 Pro SKU。如果要求使用其中一項或兩項功能，則會以 Pro SKU 計費：

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

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

擴充地點詳細資料

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

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

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

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

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

範例

下列要求會要求最多 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
}

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

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：必須與地點一併顯示的作者資訊。請參閱「出處規定」。

兩個 SKU 的回應結構相同。如需欄位詳細資料，請參閱 search_places 參考資料。

受限正式發布期間的 Pro 選項

在受限正式發布階段，只有 Pro 許可清單中的專案才能使用 Pro 選項。如果專案尚未加入許可清單，系統會忽略 Pro 選項，而非拒絕：

include_extended_details 會視為 false。
page_size 值若大於 5 (包括大於 10)，則會減少為 5。

這項要求會依 Essentials SKU 計費。如要申請存取權，請參閱「受限正式發布期間的專業選項」。

計費和配額

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

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

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