MCP Tools Reference: mapstools.googleapis.com

工具：search_places

當使用者要求尋找地點、商家、地址、位置、景點或任何其他 Google 地圖相關搜尋時，請呼叫這項工具。

輸入規定 (重要)：

  1. text_query (字串 - 必填)：主要搜尋查詢。這項資訊必須清楚定義使用者要尋找的內容。

    • 示例：'restaurants in New York'、'coffee shops near Golden Gate Park'、'SF MoMA'、'1600 Amphitheatre Pkwy, Mountain View, CA, USA'、'pets friendly parks in Manhattan, New York'、'date night restaurants in Chicago'、'accessible public libraries in Los Angeles'。
    • 如要取得特定地點的詳細資料：請加入要求的屬性 (例如 'Google Store Mountain View opening hours'、'SF MoMa phone number'、'Shoreline Park Mountain View address')。

  2. location_bias (物件 - 選用)：使用這個物件，優先顯示特定地理區域附近的結果。

    • 格式： {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • 使用方式：
      • 將半徑設為 5 公里： {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • 如要強烈偏向中心點： {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (省略 radius_meters)。

  3. language_code (字串 - 選用)：顯示搜尋結果摘要的語言。

    • 格式：雙字母語言代碼 (ISO 639-1)，後面可選擇加上底線和雙字母國家/地區代碼 (ISO 3166-1 alpha-2)，例如 en、ja、en_US、zh_CN、es_MX。如未提供語言代碼，結果會以英文顯示。

  4. region_code (字串 - 選用)：使用者的 Unicode CLDR 區域代碼。這個參數用於顯示地點詳細資料，例如特定區域的地點名稱 (如有)。根據適用法律，這項參數可能會影響結果。

    • 格式：由兩個英文字母組成的國家/地區代碼 (ISO 3166-1 alpha-2)，例如 US，CA。

工具呼叫的指示：

  • 位置資訊 (重要)：搜尋內容必須包含足夠的位置資訊。如果地點不明確 (例如只有「披薩店」)，您必須在 text_query 中指定地點 (例如 「紐約市的披薩店」)，或使用 location_bias 參數。如需消歧義，請加入城市、州/省和區域/國家/地區名稱。

  • 請盡量提供最具體且語境豐富的 text_query。

  • 只有在明確提供座標，或從使用者已知情境推斷位置資訊是適當且有助於提升結果品質時，才使用 location_bias。

下列範例示範如何使用 curl 叫用 search_places MCP 工具。

Curl 要求 
                  
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入結構定義

SearchText 的要求訊息。

SearchTextRequest

JSON 表示法 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "pageToken": string,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}
欄位
textQuery

string

必填。文字查詢。
languageCode

string

(選用步驟) 要求摘要回覆時使用的語言。如果語言代碼未指定或無法辨識，系統會傳回偏好使用英文的摘要。

例如「en」代表英文。

目前支援的語言清單：https://developers.google.com/maps/faq#languagesupport。
regionCode

string

(選用步驟) 要求來源位置的 Unicode 國家/地區代碼 (CLDR)。這個參數用於顯示地點詳細資料，例如特定區域的地點名稱 (如有)。根據適用法律，這項參數可能會影響結果。

例如「US」代表美國。

詳情請參閱 https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html。

請注意，系統目前不支援 3 位數的區域代碼。
pageSize

integer

(選用步驟) 要傳回的地點數量上限。服務傳回的產品數量可能會少於這個值。
pageToken

string

(選用步驟) 屬於接收自前一個 SearchText 呼叫的網頁權杖。提供此項目即可擷取後續網頁。

聯集欄位 _location_bias。

_location_bias 只能是下列其中一個設定：
locationBias

object (LocationBias)

可選用的區域，用於調整搜尋結果。如果 text_query 中有明確位置，系統會使用該位置來調整搜尋結果，而非這個欄位。

LocationBias

JSON 表示法 
{
  "circle": {
    object (Circle)
  }
}
欄位
circle

object (Circle)

(選用步驟) 以中心點和半徑定義的圓形。radius_meters 為選填欄位。如未設定，結果會偏向中心點。

圓形

JSON 表示法 
{
  "center": {
    object (google.type.LatLng)
  },

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}
欄位
center

object (google.type.LatLng)

必填。圓形的中心點。

聯集欄位 _radius_meters。

_radius_meters 只能是下列其中一個設定：
radiusMeters

number

圓形的半徑 (以公尺為單位)。半徑必須在 50,000 公尺內。

LatLng

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
欄位
latitude

number

緯度度數，必須介於 [-90.0, +90.0] 的範圍之間。
longitude

number

經度度數，必須介於 [-180.0, +180.0] 的範圍之間。

輸出內容的結構定義

SearchText 的回應訊息。

SearchTextResponse

JSON 表示法 
{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string,
  "nextPageToken": string
}
欄位
places[]

object (PlaceView)

僅供輸出。摘要中提及的地點清單。
summary

string

僅供輸出。搜尋結果的自然語言摘要。摘要可能包含以零為基準的引文，例如「[0]」、「[1]」、「[2]」等。這些引文會對應至 places 欄位中的相應位置。
nextPageToken

string

(選用步驟) 可做為 page_token 傳送的權杖，用於擷取後續網頁。

PlaceView

JSON 表示法 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (google.type.LatLng)
  }
  // End of list of possible types for union field _location.
}
欄位
place

string

基礎地點的資源名稱，格式為「places/{id}」。
id

string

基礎地點的地點 ID。
googleMapsLinks

object (GoogleMapsLinks)

可觸發不同 Google 地圖動作的連結。

聯集欄位 _location。

_location 只能是下列其中一個設定：
location

object (google.type.LatLng)

這個地點的位置。

LatLng

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
欄位
latitude

number

緯度度數，必須介於 [-90.0, +90.0] 的範圍之間。
longitude

number

經度度數，必須介於 [-180.0, +180.0] 的範圍之間。
JSON 表示法 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
欄位
directionsUrl

string

顯示前往該地點路線的連結。這個連結只會填入目的地位置，並使用預設的交通方式 DRIVE。
placeUrl

string

顯示這個地點的連結。
writeAReviewUrl

string

在 Google 地圖上為這個地點撰寫評論的連結。
reviewsUrl

string

連結：在 Google 地圖上顯示這個地點的評論。
photosUrl

string

連結：在 Google 地圖上顯示這個地點的評論。

工具註解

破壞性提示：❌ | 等冪提示：❌ | 唯讀提示：✅ | 開放世界提示：❌